masks 0.12.2 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 638e4da3d119c8e1841e1d8f4d87742133ac14ef28c8b1f7dbbdd55725913974
-  data.tar.gz: 5c704c90104b9fa581948029a2897e40e1e69f66573739f33aa6c3b7ceae14d4
+  metadata.gz: 24592fe5fb130abf36cb52a58a03c8184d55c428045f1698d3c061143ccffe06
+  data.tar.gz: b5bea82b253704173650c494018a16e1d5eb105fd0c3511c7d8c46141f1fe3cc
 SHA512:
-  metadata.gz: 97f6edc170dc1544af96fa847f7513a547a39422fffa2435c44f8073bcfaaaf205bf60ed4fc1f1bf82b50c968e9b21e7ff88558fc2042039df5be4ab332b8174
-  data.tar.gz: f0c0b5d58b797556ef18dffdf3a81b09e9f94407c68da642950c4578639376a109064b3efbb24d5c802edef0c138a2f079002229f35d9ae520bc2c98ff0c5439
+  metadata.gz: d154be9eb9bbb48b980fbacbd4d55b3bb9566e6375ff13619731a79c66730c923e743c7ce854f355b78d94ecc00e0ae5721b7d588d96c66ca01300e3580cd7a4
+  data.tar.gz: 19c8607bec23746660dbf8afc01a4d1ebb3a8cb11496a2f83d6a98f5ac93b121ac6cce4c6290e54a53d828e90665fb97f752ff74f71901713e1c7ca513699984

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.13.0](https://github.com/masksrb/masks/compare/gem/v0.12.2...gem/v0.13.0) (2026-11-02)
+
+
+### Features
+
+* **client:** the Ruby client checks every token against the shared contract, and an ID token's nonce, authorized party, at_hash, and max_age are checked where it is verified ([6025b73](https://github.com/masksrb/masks/commit/6025b736ef83819890dd8f6372293fd993ce328e))
+* **client:** the Ruby client raises Refused, InvalidToken, Forbidden, Unavailable, Insecure, and Foreign, the names every other SDK uses ([7d78435](https://github.com/masksrb/masks/commit/7d78435eed9b40f8da156c89890c104f23f3b70b))
+* **client:** the Ruby client words every failure from the shared error table, and a refusal or a challenge reads masks: code: description ([9674a55](https://github.com/masksrb/masks/commit/9674a5543d8154830330f49e4ba20da886d42e5e))
+
+
+### Fixes
+
+* **client:** a back-channel logout that the cache cannot keep answers JSON again, and every error_description reads without the masks: code: prefix ([30fbdec](https://github.com/masksrb/masks/commit/30fbdec0796fc5ebc7f85e421a7609267729ab45))
+
 ## [0.12.2](https://github.com/masksrb/masks/compare/gem/v0.12.1...gem/v0.12.2) (2026-10-20)
 
 

data/app/controllers/masks/rails/logouts_controller.rb

@@ -18,13 +18,13 @@ module Masks
 
         head :ok
       rescue Masks::Client::InvalidToken, Masks::Rails::Configuration::Unconfigured => e
-        refuse("invalid_request", e.message)
-      rescue Masks::Client::Unreachable, Masks::Rails::Cache::Unavailable => e
-        refuse("temporarily_unavailable", e.message, status: :service_unavailable)
+        refuse("invalid_request", e.description)
       end
 
       private
 
+        def masks_wants_json? = true
+
         def refuse(code, description, status: :bad_request)
           response.headers["Cache-Control"] = "no-store"
 

data/app/controllers/masks/rails/sessions_controller.rb

@@ -61,18 +61,12 @@ module Masks
         )
 
         identity = begin
-          masks_identity_from(tokens)
-        rescue Masks::Client::InvalidToken
-          :unverified
+          masks_identity_from(tokens, nonce: pending[:nonce], max_age: pending[:max_age])
+        rescue Masks::Client::InvalidToken => e
+          return refuse(e.code, e.description, pending)
         end
 
-        unless nonce_matches?(identity, pending[:nonce])
-          return refuse("invalid_nonce", "the id token was issued for another request", pending)
-        end
-
-        unless recent?(identity, pending[:max_age])
-          return refuse("invalid_token", "the person signed in longer ago than max_age allows", pending)
-        end
+        return refuse(*Masks::Client.failure("no_id_token"), pending) if pending[:nonce].present? && identity.nil?
 
         renew_session
         masks_store(tokens, identity: identity)
@@ -161,22 +155,6 @@ module Masks
           masks_local_path(params[:return_to])
         end
 
-        def recent?(identity, max_age)
-          Masks::Client::Verifier.recent!(identity.is_a?(Hash) ? identity : {}, max_age)
-          true
-        rescue Masks::Client::InvalidToken
-          false
-        end
-
-        def nonce_matches?(identity, sent)
-          return false if identity == :unverified
-          return true if sent.blank?
-          return false unless identity.is_a?(Hash)
-
-          held = identity["nonce"].to_s
-          held.present? && ActiveSupport::SecurityUtils.secure_compare(held, sent)
-        end
-
         def stale
           return redirect_to(masks_config.after_sign_in) if masks_signed_in? || (masks_tokens && masks_refresh!)
           return restart unless masks_wants_json? || restarted_lately?

data/lib/masks/client/claims.rb

@@ -160,17 +160,16 @@ module Masks
         held = self.organization
 
         unless held.present?
-          raise Forbidden.new("insufficient_organization", "this token names no organization",
-                              scope: Session::ORGANIZATION)
+          raise Forbidden.new(*Masks::Client.failure("no_organization"), scope: Session::ORGANIZATION)
         end
 
         if organization && held.key != organization.to_s && held.id != organization.to_s
-          raise Forbidden.new("insufficient_organization", "this token was issued for #{held.key}, not #{organization}")
+          raise Forbidden.new(*Masks::Client.failure("other_organization", held.key, organization))
         end
 
         return held if roles.flatten.empty? || held.role?(*roles)
 
-        raise Forbidden.new("insufficient_role", "#{held.role} in #{held.key} is not #{roles.flatten.join(' or ')}")
+        raise Forbidden.new(*Masks::Client.failure("other_role", held.role, held.key, roles.flatten.join(" or ")))
       end
 
       def picture
@@ -188,11 +187,7 @@ module Masks
       def permit!(scope)
         return true if permits?(scope)
 
-        raise Forbidden.new(
-          "insufficient_scope",
-          "this token does not carry #{scope}",
-          scope: scope.to_s
-        )
+        raise Forbidden.new(*Masks::Client.failure("no_scope", scope), scope: scope.to_s)
       end
 
       def expires_at

data/lib/masks/client/delegations.rb

@@ -7,14 +7,16 @@ module Masks
                     login_required interaction_required consent_required invalid_scope].freeze
 
       class Refused < Error
-        attr_reader :code, :description, :secret
+        attr_reader :secret
 
-        def initialize(code, description, secret: nil)
-          super([ code, description ].compact.join(": "))
+        def self.of(key, *values)
+          new(*Masks::Client.failure(key, *values))
+        end
 
-          @code = code
-          @description = description
+        def initialize(code, description, status: nil, secret: nil)
           @secret = secret
+
+          super(code, description, status: status)
         end
 
         def signed_in_again?
@@ -25,10 +27,10 @@ module Masks
       class Unavailable < Error
         attr_reader :secret
 
-        def initialize(message, secret: nil)
-          super(message)
-
+        def initialize(description, secret: nil)
           @secret = secret
+
+          super("temporarily_unavailable", description, status: 503)
         end
       end
 
@@ -63,14 +65,14 @@ module Masks
         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")
+          raise Refused.of("state_mismatch")
         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 == ""
+        raise Refused.of("nothing_connected", started["provider"]) if held.nil?
+        raise Refused.of("no_refresh_for_connection") if tokens.refresh_token.to_s == ""
 
         Held.new(
           connection: held["connection"], provider: held["provider"], provider_name: held["provider_name"],
@@ -99,11 +101,11 @@ module Masks
           yield
         rescue Unregistered
           raise
-        rescue Rejected => e
+        rescue Masks::Client::Refused => 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 Refused.new(e.code, e.description, status: e.status, secret: secret)
+        rescue Masks::Client::Unavailable => e
           raise Unavailable.new(e.message, secret: secret)
         end
 

data/lib/masks/client/device.rb

@@ -12,7 +12,7 @@ module Masks
         missing = REQUIRED.find { |field| body[field].to_s.empty? }
 
         if missing
-          raise Rejected.new(
+          raise Refused.new(
             body["error"] || "invalid_device_authorization_response",
             body["error_description"] || "the device authorization endpoint answered without a #{missing}"
           )

data/lib/masks/client/embedded.rb

@@ -39,14 +39,14 @@ module Masks
 
           unless worker.join(HTTP::READ_TIMEOUT)
             worker.kill
-            raise Unreachable, "#{uri.host} did not answer within #{HTTP::READ_TIMEOUT} seconds"
+            raise Unavailable, Masks::Client.saying("unreachable", uri.host)
           end
 
           worker.value
         rescue Error
           raise
         rescue StandardError => e
-          raise Unreachable, "#{uri.host} failed inside this process (#{e.class})"
+          raise Unavailable, Masks::Client.saying("unreachable", uri.host)
         end
 
         def collected(status, headers, body, uri, limit)
@@ -54,7 +54,7 @@ module Masks
 
           body.each do |chunk|
             held << chunk.to_s.b
-            raise Error, "#{uri.host} answered with more than #{limit} bytes" if limit && held.bytesize > limit
+            raise Refused.new("server_error", "#{uri.host} answered with more than #{limit} bytes") if limit && held.bytesize > limit
           end
 
           [ status.to_i, headers, held ]

data/lib/masks/client/enrollment.rb

@@ -5,7 +5,7 @@ module Masks
 
       def self.issued(body)
         if body["initial_access_token"].to_s.empty?
-          raise Rejected.new(
+          raise Refused.new(
             body["error"] || "invalid_enrollment_response",
             body["error_description"] || "the enrollment endpoint answered without an initial_access_token"
           )

data/lib/masks/client/errors.rb

@@ -1,28 +1,39 @@
 module Masks
   module Client
-    class Error < StandardError; end
+    def self.failure(key, *values)
+      code, template = FAILURES.fetch(key.to_sym)
 
-    class Unreachable < Error; end
-
-    class Foreign < Error; end
-
-    class Insecure < Error; end
+      [ code, format(template, *values) ]
+    end
 
-    class ReplayUnavailable < Error; end
+    def self.saying(key, *values)
+      failure(key, *values).last
+    end
 
-    class Rejected < Error
-      attr_reader :code, :description, :status
+    def self.worded(code, description)
+      [ "masks", code, description ].reject { |part| part.to_s.empty? }.join(": ")
+    end
 
-      def initialize(code, description, status: nil)
-        super([ code, description ].compact.join(": "))
+    class Error < StandardError
+      attr_reader :code, :description, :status, :uri
 
-        @code = code
+      def initialize(code, description = nil, status: nil, uri: nil)
+        @code = code.to_s
         @description = description
         @status = status
+        @uri = uri
+
+        super(Masks::Client.worded(@code, description))
+      end
+    end
+
+    class Refused < Error
+      def self.of(key, *values)
+        new(*Masks::Client.failure(key, *values))
       end
     end
 
-    class Unregistered < Rejected
+    class Unregistered < Refused
       CODE = "invalid_client".freeze
 
       def self.raised_by?(body)
@@ -30,19 +41,22 @@ module Masks
       end
     end
 
-    class InvalidToken < Error; end
+    class InvalidToken < Error
+      def self.of(key, *values)
+        code, description = Masks::Client.failure(key, *values)
 
-    class Challenge < Error
-      attr_reader :code, :description, :status, :scope
+        new(description, code: code, missing: key.to_s == "no_token")
+      end
 
-      def initialize(code, description, status:, scope: nil, dpop: false)
-        super([ code, description ].compact.join(": "))
+      def initialize(description, code: "invalid_token", missing: false, dpop: nil)
+        @missing = missing
+        @dpop = dpop.nil? ? code == "invalid_dpop_proof" : dpop
 
-        @code = code
-        @description = description
-        @status = status
-        @scope = scope
-        @dpop = dpop
+        super(code, description, status: 401)
+      end
+
+      def missing?
+        @missing
       end
 
       def dpop?
@@ -50,21 +64,47 @@ module Masks
       end
     end
 
-    class Unauthenticated < Challenge
-      def initialize(description = "a bearer token is required", code: nil)
-        super(code, description, status: 401)
+    class Forbidden < Error
+      attr_reader :scope
+
+      def self.of(key, *values)
+        new(*Masks::Client.failure(key, *values))
+      end
+
+      def initialize(code, description, scope: nil)
+        @scope = scope
+
+        super(code, description, status: 403)
+      end
+    end
+
+    class Unavailable < Error
+      def self.of(key, *values)
+        new(Masks::Client.saying(key, *values))
+      end
+
+      def initialize(description)
+        super("temporarily_unavailable", description, status: 503)
       end
     end
 
-    class Unauthorized < Challenge
-      def initialize(description, code: "invalid_token", dpop: false)
-        super(code, description, status: 401, dpop: dpop)
+    class Insecure < Error
+      def self.of(key, *values)
+        new(Masks::Client.saying(key, *values))
+      end
+
+      def initialize(description)
+        super("insecure_url", description)
       end
     end
 
-    class Forbidden < Challenge
-      def initialize(code, description, scope: nil)
-        super(code, description, status: 403, scope: scope)
+    class Foreign < Error
+      def self.of(key, *values)
+        new(Masks::Client.saying(key, *values))
+      end
+
+      def initialize(description)
+        super("foreign_origin", description)
       end
     end
   end

data/lib/masks/client/failures.rb

@@ -0,0 +1,81 @@
+module Masks
+  module Client
+    FAILURES = {
+      no_token: [ "invalid_token", "the request carries no token" ],
+      not_a_jwt: [ "invalid_token", "that token is not a signed JWT" ],
+      no_key: [ "invalid_token", "%s publishes no key %s" ],
+      not_signed_by: [ "invalid_token", "that token was not signed by %s" ],
+      not_an_algorithm: [ "invalid_token", "%s is not an algorithm masks signs with" ],
+      wrong_type: [ "invalid_token", "that token is typed %s, not %s" ],
+      expired: [ "invalid_token", "that token has expired" ],
+      not_valid_yet: [ "invalid_token", "that token is not valid yet" ],
+      issued_in_future: [ "invalid_token", "that token was issued in the future" ],
+      other_issuer: [ "invalid_token", "that token was issued by another server" ],
+      other_audience: [ "invalid_token", "that token was issued for another app" ],
+      missing_claims: [ "invalid_token", "that token is missing %s" ],
+      unverified: [ "invalid_token", "that token could not be verified" ],
+      too_old: [ "invalid_token", "the person signed in longer ago than max_age allows" ],
+      bound_as_bearer: [ "invalid_token", "that token is held to a key, so it is presented as DPoP with a proof" ],
+      unbound_as_dpop: [ "invalid_token", "that token is held to no key, so it is presented as Bearer" ],
+      not_active: [ "invalid_token", "the issuer reports this token is not active" ],
+      no_id_token: [ "invalid_token", "the token endpoint answered without an ID token" ],
+      id_token_other_sign_in: [ "invalid_token", "that ID token was issued for another sign-in" ],
+      id_token_other_client: [ "invalid_token", "that ID token was issued to another client" ],
+      id_token_several_audiences: [ "invalid_token", "that ID token names several audiences and was not issued to this client" ],
+      id_token_other_access_token: [ "invalid_token", "that ID token was issued with another access token" ],
+      id_token_other_organization: [ "invalid_token", "that ID token does not name the organization %s" ],
+      not_a_logout: [ "invalid_token", "that token is not about a logout" ],
+      logout_names_nobody: [ "invalid_token", "that logout token names neither a subject nor a session" ],
+      logout_with_nonce: [ "invalid_token", "that logout token carries a nonce, so it is an ID token" ],
+      one_proof: [ "invalid_dpop_proof", "exactly one DPoP proof is required" ],
+      proof_not_a_jwt: [ "invalid_dpop_proof", "that proof is not a signed JWT" ],
+      proof_type: [ "invalid_dpop_proof", "a proof is typed %s" ],
+      proof_algorithm: [ "invalid_dpop_proof", "%s is not an algorithm a proof may use" ],
+      proof_no_key: [ "invalid_dpop_proof", "a proof carries the public key that signed it" ],
+      proof_key_private: [ "invalid_dpop_proof", "a proof key is public" ],
+      proof_key_unreadable: [ "invalid_dpop_proof", "that proof carries a key this API cannot read" ],
+      proof_unsigned: [ "invalid_dpop_proof", "that proof was not signed by the key it carries" ],
+      proof_other_key: [ "invalid_dpop_proof", "that proof was signed by another key than the token is held to" ],
+      proof_other_token: [ "invalid_dpop_proof", "that proof was made for another token" ],
+      proof_other_method: [ "invalid_dpop_proof", "that proof was made for another method" ],
+      proof_other_url: [ "invalid_dpop_proof", "that proof was made for another URL" ],
+      proof_not_now: [ "invalid_dpop_proof", "that proof was not made just now" ],
+      proof_no_jti: [ "invalid_dpop_proof", "a proof carries a jti" ],
+      proof_replayed: [ "invalid_dpop_proof", "that proof has already been used" ],
+      no_scope: [ "insufficient_scope", "this token does not carry %s" ],
+      not_granted: [ "insufficient_scope", "masks did not grant %s" ],
+      no_privilege: [ "insufficient_scope", "this account does not hold the %s privilege" ],
+      no_organization: [ "insufficient_organization", "this sign-in names no organization" ],
+      other_organization: [ "insufficient_organization", "this sign-in is for %s, and this needs %s" ],
+      other_role: [ "insufficient_role", "%s in %s is not %s" ],
+      unreachable: [ "temporarily_unavailable", "%s could not be reached" ],
+      keys_unreachable: [ "temporarily_unavailable", "%s could not be reached for its keys" ],
+      replay_store_unreachable: [ "temporarily_unavailable", "the replay store could not be reached" ],
+      replay_store_answer: [ "temporarily_unavailable", "the replay store answered with something other than true or false" ],
+      store_unreachable: [ "temporarily_unavailable", "the store could not be reached" ],
+      not_checked: [ "temporarily_unavailable", "the token could not be checked" ],
+      plain_http: [ "insecure_url", "plain http is allowed only on this machine: %s" ],
+      not_http: [ "insecure_url", "%s is not an http or https URL" ],
+      other_origin: [ "foreign_origin", "that URL belongs to another origin: %s" ],
+      tokens_only_for: [ "foreign_origin", "tokens are held only for %s, not %s" ],
+      answered_status: [ "server_error", "%s answered %s" ],
+      not_json: [ "server_error", "%s answered with something other than JSON" ],
+      not_an_object: [ "server_error", "%s answered with JSON that is not an object" ],
+      too_large: [ "server_error", "%s answered with more than a megabyte" ],
+      publishes_nothing: [ "invalid_issuer", "%s publishes no %s" ],
+      names_another: [ "invalid_issuer", "%s publishes a document naming %s" ],
+      resource_names_another: [ "invalid_target", "%s publishes metadata naming %s" ],
+      state_mismatch: [ "invalid_state", "the state did not match the one this sign-in started with" ],
+      nothing_in_flight: [ "invalid_request", "this browser has no sign-in in flight" ],
+      no_callback_code: [ "invalid_request", "the callback carried no code" ],
+      code_expired: [ "expired_token", "the code expired before anyone approved it" ],
+      no_refresh_token: [ "invalid_grant", "there is no refresh token to renew these tokens with" ],
+      not_held_to_key: [ "invalid_dpop_proof", "the token endpoint answered with a token that is not held to this key" ],
+      no_avatars: [ "invalid_style", "%s does not serve %s avatars" ],
+      not_connected: [ "handshake_required", "this app has not shaken hands with %s" ],
+      nothing_connected: [ "access_denied", "masks connected nothing for %s" ],
+      no_refresh_for_connection: [ "invalid_grant", "masks issued no refresh token to keep the connection with" ],
+      delegation_not_answering: [ "temporarily_unavailable", "masks is not answering" ]
+    }.freeze
+  end
+end

data/lib/masks/client/handshake.rb

@@ -90,7 +90,7 @@ module Masks
           return if present?(held) && present?(returned) &&
                     OpenSSL.secure_compare(returned.to_s, held.to_s)
 
-          refuse("invalid_state", "the handshake did not match this browser")
+          refuse(*Masks::Client.failure("state_mismatch"))
         end
 
         def verify_issuer!(named)
@@ -101,7 +101,7 @@ module Masks
         end
 
         def refuse(code, description)
-          raise Rejected.new(code.to_s, description.to_s)
+          raise Refused.new(code.to_s, description.to_s)
         end
 
         def normalize(params)

data/lib/masks/client/http.rb

@@ -77,7 +77,7 @@ module Masks
           read_timeout: READ_TIMEOUT
         ) { |http| limit ? limited(http, request, limit) : http.request(request) }
       rescue SystemCallError, SocketError, Net::OpenTimeout, Net::ReadTimeout, OpenSSL::SSL::SSLError => e
-        raise Unreachable, "#{uri.host} is unreachable (#{e.class})"
+        raise Unavailable, Masks::Client.saying("unreachable", uri.host)
       end
 
       def checked(uri)
@@ -85,11 +85,10 @@ module Masks
         return uri if uri.is_a?(URI::HTTP) && !uri.host.to_s.empty? && (Masks::Client.plain_http? || loopback?(uri.hostname))
 
         if uri.is_a?(URI::HTTP)
-          raise Insecure, "#{Nonces.origin(uri)} is plain http, which masks allows only for loopback hosts " \
-                          "unless Masks::Client.plain_http is set"
+          raise Insecure, Masks::Client.saying("plain_http", Nonces.origin(uri))
         end
 
-        raise Error, "#{uri} is not an http or https URL"
+        raise Insecure.of("not_http", uri)
       end
 
       def loopback?(host)
@@ -108,7 +107,7 @@ module Masks
 
           response.read_body do |chunk|
             body << chunk
-            raise Error, "#{request.uri.host} answered with more than #{limit} bytes" if body.bytesize > limit
+            raise Refused.new("server_error", "#{request.uri.host} answered with more than #{limit} bytes") if body.bytesize > limit
           end
 
           response.body = body
@@ -119,13 +118,10 @@ module Masks
         body = decoded(response)
 
         unless response.is_a?(Net::HTTPSuccess)
-          refusal = Unregistered.raised_by?(body) ? Unregistered : Rejected
+          refusal = Unregistered.raised_by?(body) ? Unregistered : Refused
+          code, description = refused_with(body, response)
 
-          raise refusal.new(
-            body["error"] || "http_#{response.code}",
-            body["error_description"] || response.message,
-            status: response.code.to_i
-          )
+          raise refusal.new(code, description, status: response.code.to_i)
         end
 
         body
@@ -140,13 +136,17 @@ module Masks
         return held if held.is_a?(Hash)
         return {} unless response.is_a?(Net::HTTPSuccess)
 
-        raise Rejected.new("invalid_response", "#{origin(response)} answered with JSON that is not an object",
-                           status: response.code.to_i)
+        raise Refused.new(*Masks::Client.failure("not_an_object", origin(response)), status: response.code.to_i)
       rescue JSON::ParserError
         return {} unless response.is_a?(Net::HTTPSuccess)
 
-        raise Rejected.new("invalid_response", "#{origin(response)} answered with something other than JSON",
-                           status: response.code.to_i)
+        raise Refused.new(*Masks::Client.failure("not_json", origin(response)), status: response.code.to_i)
+      end
+
+      def refused_with(body, response)
+        return Masks::Client.failure("answered_status", origin(response), response.code.to_i) if body["error"].to_s.empty?
+
+        [ body["error"], body["error_description"] || response.message ]
       end
 
       def origin(response)

data/lib/masks/client/id_token.rb

@@ -0,0 +1,35 @@
+module Masks
+  module Client
+    class IdToken
+      REQUIRED = %w[iss sub aud exp iat].freeze
+
+      class << self
+        def verify(token, issuer:, client_id:, nonce: nil, access_token: nil, max_age: nil)
+          claims = Verifier.new(issuer, audience: client_id).verify(token, required: REQUIRED, typ: Verifier::ID_TOKEN)
+
+          raise InvalidToken.of("id_token_several_audiences") if Array(claims["aud"]).size > 1 && !claims.key?("azp")
+          raise InvalidToken.of("id_token_other_client") if claims.key?("azp") && claims["azp"] != client_id
+          raise InvalidToken.of("id_token_other_sign_in") if nonce && !same?(claims["nonce"], nonce)
+
+          if access_token && claims.key?("at_hash") && !same?(claims["at_hash"], half_hash(access_token))
+            raise InvalidToken.of("id_token_other_access_token")
+          end
+
+          Verifier.recent!(claims, max_age)
+        end
+
+        def half_hash(value)
+          digest = Digest::SHA256.digest(value.to_s)
+
+          Base64.urlsafe_encode64(digest[0, digest.bytesize / 2], padding: false)
+        end
+
+        private
+
+          def same?(held, wanted)
+            held.is_a?(String) && !held.empty? && OpenSSL.secure_compare(held, wanted.to_s)
+          end
+      end
+    end
+  end
+end

data/lib/masks/client/introspection.rb

@@ -19,14 +19,14 @@ module Masks
 
       def permit!(scope)
         unless active?
-          raise Unauthorized.new("the issuer reports this token is not active")
+          raise InvalidToken.new(Masks::Client.saying("not_active"))
         end
 
         super
       end
 
       def member!(*roles, organization: nil)
-        raise Unauthorized.new("the issuer reports this token is not active") unless active?
+        raise InvalidToken.new(Masks::Client.saying("not_active")) unless active?
 
         super
       end