masks 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c0b13e1f370033e4c4512becb39b4d96e4b9d28b39b7f1e773592138626d1151
-  data.tar.gz: 8540eeecb1b448047198d5da57e5978d0e4ec249138334e7c39d41a719854a99
+  metadata.gz: e082a74bac3486cd6f3291ef29a91dd0ecc325a2f3938465a44722c66e2363b0
+  data.tar.gz: 22b5932157ba69c6c8401ab71b54ab0be1c640ae0f5da67f0ffa04c1fa1d15fa
 SHA512:
-  metadata.gz: fc1b4981446fdc5282e21c00c93a63cbc124d3c675512172a849cdd698f0a52839fce8098fdde6443814131f198eef5829d1dd52416e02bb51ef95f7d5fb634a
-  data.tar.gz: e40f6519f1c22fefa134217cff31701617551feed13e374f1d801307c2f021cb21eba5b85adc4eb9d28e133e855c4aad4cc05caa4749d34fadd9d7e833493cc1
+  metadata.gz: ed991af661f602ac3e32c190575bcb8f03f1f4ad5dce0d4006516ad2587e53efaa15c75b51a480b9ccbb1634f88844cc3a32ceb4c516313f93b928d01298d71f
+  data.tar.gz: ef37a84b598962d464d24c68e33db41645ab6e85be67b34d13bae1061f061db0ce2a0180d1b4e82ec77c98a17bfcdbee4812fd2a855783ae2868211e8ff54741

data/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## [0.11.0](https://github.com/masksrb/masks/compare/gem/v0.10.0...gem/v0.11.0) (2026-10-13)
+
+
+### Features
+
+* **client:** a session holds its tokens to a DPoP key and proves it on every token request ([be3732c](https://github.com/masksrb/masks/commit/be3732cec2873fed75d8c70591f9bb1a2dcfb93c))
+* **client:** a session runs the device flow and polls until somebody approves the code ([cd96836](https://github.com/masksrb/masks/commit/cd96836a9d97049f80b9efcf6eec8335e7650a6a))
+* **client:** config.replay names one store of seen DPoP proofs for every process of a Rails app ([e3baf5a](https://github.com/masksrb/masks/commit/e3baf5a04b652ec2205bbc88004cb37b78ac9b0e))
+* **client:** Masks::Client.embed answers an issuer's requests inside the process, for an app that mounts masks and signs in through it ([7473031](https://github.com/masksrb/masks/commit/74730318cd335a74207b1fea0156b646e61d74c1))
+* **client:** Session#enroll asks masks for an enrollment token that a machine spends once to register its own key ([be52734](https://github.com/masksrb/masks/commit/be52734f7d470140749bf2f2d208d81ca85bc42d))
+* **client:** Session#unenroll archives a machine the app enrolled and revokes its tokens ([2743890](https://github.com/masksrb/masks/commit/2743890063f1e3818f8acb29048bb549f1b94220))
+* **server:** /manage, the sign-in pages, and the docs share one palette and one font stack ([17efe87](https://github.com/masksrb/masks/commit/17efe87c81c14d7541a37292bf58ba242836eca5))
+
+
+### Fixes
+
+* **client:** signing out everywhere returns through the handshake callback masks registered, so masks no longer refuses it ([6eb6e70](https://github.com/masksrb/masks/commit/6eb6e7067d43803f0ac8dcfbc04e2d8057ac2ca0))
+* **client:** the gem speaks only https off loopback, reads at most 1 MB, and answers 503 when its replay store is down ([6c03a43](https://github.com/masksrb/masks/commit/6c03a430a500d3476e018cf650bf093ad2aca102))
+
+
+### Documentation
+
+* each language has a group under Reference, with an overview, a page per framework, and its API reference ([64b7837](https://github.com/masksrb/masks/commit/64b7837e0484d11ddd5b4d926fc4aa800c06ed81))
+* each SDK keeps a TODO of the cleanups, security follow-ups, and testing left from the framework integrations ([4c4353b](https://github.com/masksrb/masks/commit/4c4353b63713700034c78f3d3c0b3b45ac7b50b3))
+
+
+### Refactoring
+
+* **server:** /manage derives its surfaces from the shared palette, and --label folds into --brass ([c00d32b](https://github.com/masksrb/masks/commit/c00d32b821cc99b8cbc2903a7a4c0c08aa2770bd))
+
 ## [0.10.0](https://github.com/masksrb/masks/compare/gem/v0.9.2...gem/v0.10.0) (2026-10-11)
 
 

data/README.md

@@ -22,7 +22,7 @@ bin/rails generate masks:install --resource https://app.example.com
 
 That mounts the engine at `/auth`, writes `config/initializers/masks.rb`, and gitignores
 the file credentials land in. Set `MASKS_ISSUER`, start the app, and open
-`/auth/handshake`. [Rails apps](https://masks.pages.dev/guides/rails/) walks through the rest.
+`/auth/handshake`. [Rails apps](https://masks.pages.dev/reference/ruby/) walks through the rest.
 
 ### The handshake
 
@@ -94,7 +94,7 @@ sign-in. When a signed-in person lacks one, the browser goes through masks once
 comes back, and the action answers `403` when masks does not grant it. A missing role or organization
 answers `403` at once. `masked.privilege?(:admin)` and `masked.privileges` tell a view what the sign-in
 holds, and `/auth/session` answers `privileges`. See
-[privileges](https://masks.pages.dev/guides/rails/#privileges).
+[privileges](https://masks.pages.dev/reference/ruby/#privileges).
 
 `config.authenticate_everything = true` includes `Authentication` on every controller. Otherwise
 include it where it applies.
@@ -102,7 +102,7 @@ include it where it applies.
 ### A single-page app in front of it
 
 `GET /auth/session` answers identity, tenant, and scopes as JSON, or `401` with where to send the
-browser. [`@masks/client`](https://masks.pages.dev/reference/browser/) reads it:
+browser. [`@masks/client`](https://masks.pages.dev/reference/javascript/client/) reads it:
 
 ```js
 import { createSession } from "@masks/client"
@@ -225,6 +225,7 @@ a subdomain-per-tenant host needs.
 | `sign_out_of_issuer` | make every sign-out an RP-initiated logout |
 | `session_key` | the session key the tokens live under |
 | `delegates` / `delegation_redirect_uri` | ask for delegation in the handshake, and where connecting an account returns |
+| `replay` | where seen DPoP proofs are remembered, any object with `first?(key, expires_in:)`, this process's memory by default |
 
 ## Any Ruby app
 
@@ -249,14 +250,128 @@ Hold `started[:state]`, `started[:nonce]`, and `started[:verifier]` in the sessi
 browser to `started[:url]`. `start` sends a nonce only when the scope includes `openid`. Check the
 returned `state` yourself, and compare `identity["nonce"]` with the one you held.
 
-`Session` also has `refresh`, `exchange`, `client_credentials`, `revoke`, `introspect`, `userinfo`,
-and `end_session_url`. It authenticates with `client_secret`, or with `private_key` and `key_id` for
-`private_key_jwt`.
+`Session` also has `refresh`, `exchange`, `client_credentials`, `device_authorization`,
+`await_device`, `enroll`, `unenroll`, `revoke`, `introspect`, `userinfo`, `end_session_url`, and
+`transport`. It authenticates with `client_secret`, or with `private_key` and `key_id` for
+`private_key_jwt`. A `Masks::Client::Key` passed as `private_key` names itself by its thumbprint, so
+`key_id` can be left out.
+
+`userinfo` takes `Tokens` or an access token string. A string and a `Bearer` token go as `Bearer`.
+A DPoP-bound token goes as `Authorization: DPoP` with a proof from the session's `dpop:` key, and
+raises `Masks::Client::Error` when the session holds no key.
+
+An app that has claimed a namespace enrolls a machine with `enroll`. It returns an
+`Enrollment` whose `initial_access_token` the machine spends once to register its own public key.
+
+```ruby
+enrollment = session.enroll(scope: "xixo:agent", name: "nas", expires_in: 900)
+enrollment.initial_access_token
+```
+
+`unenroll` takes the machine's client ID. masks archives the machine and revokes its tokens, and
+refuses a client the app did not enroll.
+
+```ruby
+session.unenroll(machine_client_id)
+```
+
+### A machine
+
+A machine enrolled by an app makes two P-256 keys: one to sign its client assertions, and one to
+hold its tokens with DPoP. It registers the public half of the first with the app's initial access
+token, and keeps both private halves to itself.
+
+```ruby
+key = Masks::Client::Key.generate
+dpop = Masks::Client::Key.generate
+
+registration = Masks::Client::Registration.create(
+  "https://demo.auth.example.com", token: initial_access_token,
+  name: "nas", jwks: key, token_endpoint_auth_method: "private_key_jwt",
+  grant_types: [ "client_credentials" ], dpop_bound_access_tokens: true
+)
+
+File.write("machine.json", { "client_id" => registration.client_id, "key" => key.to_h,
+                             "dpop" => dpop.to_h }.to_json, perm: 0o600)
+
+session = registration.session(private_key: key, dpop: dpop)
+tokens = session.client_credentials(scope: "xixo:agent")
+tokens.bound?
+```
+
+`Registration.create` sends `grant_types` and `response_types` only when they are given, and masks
+fills in the rest: an enrolled machine gets `client_credentials`, and an open registration gets
+`authorization_code` and `code`. `jwks:` takes a `Key`, a list of them, or a JWK Set. `Key#jwks` and `Key#public_jwk` hold only the
+public half, and `Key#to_h` holds the private one. `Key.parse` reads a key back from that hash, its
+JSON, or a PEM. A key on another curve, or a public key, raises `ArgumentError`.
+
+`Registration.create` with a `token:` posts to `/register` even when discovery publishes no
+`registration_endpoint`, because a tenant that turns open registration off still redeems initial
+access tokens there. `read`, `update`, and `delete` raise `Masks::Client::Foreign` when the
+`registration_client_uri` names an origin other than the issuer's, and send nothing.
+
+A `Session` given `dpop:` sends a new DPoP proof with every request to the token endpoint:
+`complete`, `client_credentials`, `refresh`, `exchange`, and `await_device`. A server that answers
+`use_dpop_nonce` with a `DPoP-Nonce` header gets one retry carrying that nonce, and the nonce is
+kept for that origin's next request. A token endpoint that answers a proven request with a `Bearer`
+token is refused with `invalid_dpop_proof`. Revocation, introspection, enrollment, and device
+authorization are sent without a proof.
+
+`transport` sends requests to a resource with those tokens. It takes the origins it may send them to
+and raises `Masks::Client::Foreign` for any other URL before it fetches a token. An origin in plain
+`http` follows the same rule as the issuer, and raises `Masks::Client::Insecure` when the transport
+is built. A resource's answers are not limited to 1 MB.
+
+```ruby
+api = session.transport("https://app.example.com", scope: "xixo:agent")
+
+response = api.get("https://app.example.com/mcp/feeds?page=2")
+api.post("https://app.example.com/mcp/feeds", body: { "name" => "notes" })
+```
+
+Each request carries `Authorization: DPoP` and a proof naming the method, the URL without its query,
+and the token's hash in `ath`. A resource that answers `401` with `use_dpop_nonce` in
+`WWW-Authenticate` and a new `DPoP-Nonce` is asked once more. The answer is a `Net::HTTPResponse`,
+which the transport returns whatever its status. A `Bearer` token goes as `Bearer` with no proof.
+
+Without `tokens:`, the transport asks for `client_credentials` with the `scope` and `resource` it was
+given, and again when they expire. With `tokens:`, it renews them with their refresh token, keeps that
+refresh token when the server does not rotate it, and yields the new tokens so they can be stored:
+
+```ruby
+api = session.transport("https://app.example.com", tokens: held) { |tokens| store(tokens.to_h) }
+```
+
+`Masks::Client::Transport.new(*origins, tokens:, key:)` builds one around tokens you already hold.
+
+### The device flow
+
+A device with no browser asks for a code, shows it, and polls until somebody approves it:
+
+```ruby
+device = session.device_authorization(scope: %w[openid offline_access], resource: "https://app.example.com/mcp")
+
+puts "Open #{device.verification_uri} and enter #{device.user_code}"
+
+tokens = session.await_device(device)
+```
+
+`await_device` waits `interval` seconds between polls, five when the server names none, and five
+seconds longer after each `slow_down`. It keeps polling through `authorization_pending`. It raises
+`Masks::Client::Rejected` with the server's code for `access_denied`, `expired_token`, or any other
+refusal, and raises `expired_token` without polling once `device.expires_at` has passed. A session
+holding a DPoP key proves each poll, and the tokens it returns are held to that key.
 
 Discovery and JWKS are cached for five minutes and refetched on an unknown `kid`, so a key rotation
 needs no restart. The cache lives on the `Issuer`, so use `Masks::Client::Issuer.resolve` instead
 of constructing one per request.
 
+Every request the gem makes goes over `https`, or plain `http` to `localhost`, a `*.localhost`
+name, or a loopback address. Any other `http` URL raises `Masks::Client::Insecure` before anything is
+sent. A deployment that reaches its issuer over a private network in plain `http` sets
+`Masks::Client.plain_http = true`. Answers from the issuer are read up to 1 MB, and an answer that
+is not a JSON object raises `Masks::Client::Rejected` with the code `invalid_response`.
+
 ### The handshake
 
 The flow that connects a first-party app:
@@ -297,8 +412,13 @@ claims.tenant.subdomain
 accepted only as `Authorization: DPoP` with a proof signed by that key for this method, URL, and
 token, made within the last minute and never seen before. `proof`, `method`, and `url` are what it
 checks the proof against. Seen proofs are kept in the process's memory. A deployment with several
-processes passes `replay:` to `Resource.new`, any object whose `first?(key, expires_in:)` answers true
-only once for each key.
+processes passes `replay:` to `Resource.new`, or sets `config.replay` in a Rails app, to any object
+whose `first?(key, expires_in:)` answers true only once for each key across every process.
+
+When that store raises, `authenticate` raises `Masks::Client::ReplayUnavailable`, which is not a
+challenge. The Rack middleware and a Rails controller answer `503` with `temporarily_unavailable`
+and no `WWW-Authenticate` header, so a client keeps a token that is still good. A proof the store
+has already seen is still refused with `401`.
 
 A refusal builds the RFC 6750 challenge carrying `resource_metadata` and the scopes it would have
 accepted:

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

@@ -1,6 +1,7 @@
 module Masks
   module Rails
     class HandshakesController < BaseController
+      prepend_before_action :signed_out_upstream, only: :callback
       before_action :require_unconfigured_or_signed_in
       before_action :require_unconfigured_or_manager
 
@@ -44,6 +45,13 @@ module Masks
 
       private
 
+        def signed_out_upstream
+          return if params[:initial_access_token].present? || params[:error].present?
+          return stale if masks_farewells.claim(params[:state].to_s).nil?
+
+          redirect_to masks_after_sign_out_path
+        end
+
         def begin!
           pending = masks_handshakes.open
           started = masks_config.handshake_for(request).start(state: pending.id)

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

@@ -73,12 +73,13 @@ module Masks
 
       def destroy
         everywhere = masks_config.sign_out_of_issuer || params[:everywhere].present?
-        upstream = everywhere ? masks_logout_url : nil
 
         revoke_refresh_token
         masks_forget
         reset_session
 
+        upstream = everywhere ? masks_sign_out_upstream : nil
+
         if masks_wants_json?
           render json: { "signed_in" => false, "logout_url" => upstream }.compact
         else

data/lib/masks/client/device.rb

@@ -0,0 +1,47 @@
+module Masks
+  module Client
+    class Device
+      GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code".freeze
+      INTERVAL = 5
+      REQUIRED = %w[device_code user_code verification_uri].freeze
+
+      attr_reader :device_code, :user_code, :verification_uri, :verification_uri_complete, :expires_in, :interval,
+                  :obtained_at
+
+      def self.issued(body)
+        missing = REQUIRED.find { |field| body[field].to_s.empty? }
+
+        if missing
+          raise Rejected.new(
+            body["error"] || "invalid_device_authorization_response",
+            body["error_description"] || "the device authorization endpoint answered without a #{missing}"
+          )
+        end
+
+        new(body)
+      end
+
+      def initialize(body)
+        @device_code = body["device_code"]
+        @user_code = body["user_code"]
+        @verification_uri = body["verification_uri"]
+        @verification_uri_complete = body["verification_uri_complete"]
+        @expires_in = body["expires_in"].to_i
+        @interval = body["interval"].to_i
+        @obtained_at = Time.now.to_i
+      end
+
+      def expires_at
+        obtained_at + expires_in
+      end
+
+      def expired?
+        Time.now.to_i > expires_at
+      end
+
+      def inspect
+        "#<#{self.class.name} #{user_code} for #{verification_uri}>"
+      end
+    end
+  end
+end

data/lib/masks/client/embedded.rb

@@ -0,0 +1,125 @@
+require "stringio"
+
+module Masks
+  module Client
+    class Embedded
+      LOOPBACK = "127.0.0.1".freeze
+      DROPPED = %w[host accept-encoding connection content-length].freeze
+
+      attr_reader :app
+
+      def initialize(app, &serves)
+        raise ArgumentError, "an embedded issuer needs the app that serves it" if app.nil?
+        raise ArgumentError, "an embedded issuer needs a block naming the URLs it serves" if serves.nil?
+
+        @app = app
+        @serves = serves
+      end
+
+      def serves?(uri)
+        @serves.call(uri) ? true : false
+      end
+
+      def deliver(request, limit: nil)
+        uri = request.uri
+        status, headers, body = answer(environment(request, uri), uri, limit)
+
+        parsed(request, raw(status, headers, body))
+      end
+
+      def inspect
+        "#<#{self.class.name} #{app.inspect}>"
+      end
+
+      private
+
+        def answer(env, uri, limit)
+          worker = Thread.new { collected(*app.call(env), uri, limit) }
+          worker.report_on_exception = false
+
+          unless worker.join(HTTP::READ_TIMEOUT)
+            worker.kill
+            raise Unreachable, "#{uri.host} did not answer within #{HTTP::READ_TIMEOUT} seconds"
+          end
+
+          worker.value
+        rescue Error
+          raise
+        rescue StandardError => e
+          raise Unreachable, "#{uri.host} failed inside this process (#{e.class})"
+        end
+
+        def collected(status, headers, body, uri, limit)
+          held = "".b
+
+          body.each do |chunk|
+            held << chunk.to_s.b
+            raise Error, "#{uri.host} answered with more than #{limit} bytes" if limit && held.bytesize > limit
+          end
+
+          [ status.to_i, headers, held ]
+        ensure
+          body.close if body.respond_to?(:close)
+        end
+
+        def environment(request, uri)
+          input = request.body.to_s.b
+
+          env = {
+            "REQUEST_METHOD" => request.method,
+            "SCRIPT_NAME" => "",
+            "PATH_INFO" => uri.path.to_s.empty? ? "/" : uri.path,
+            "QUERY_STRING" => uri.query.to_s,
+            "SERVER_NAME" => uri.host,
+            "SERVER_PORT" => uri.port.to_s,
+            "SERVER_PROTOCOL" => "HTTP/1.1",
+            "REMOTE_ADDR" => LOOPBACK,
+            "HTTP_HOST" => uri.port == uri.default_port ? uri.host : "#{uri.host}:#{uri.port}",
+            "HTTPS" => uri.scheme == "https" ? "on" : "off",
+            "rack.url_scheme" => uri.scheme,
+            "rack.input" => StringIO.new(input),
+            "rack.errors" => $stderr
+          }
+
+          env["CONTENT_LENGTH"] = input.bytesize.to_s unless input.empty?
+
+          request.each_header do |name, value|
+            next if DROPPED.include?(name)
+
+            key = name.upcase.tr("-", "_")
+            env[key == "CONTENT_TYPE" ? key : "HTTP_#{key}"] = value
+          end
+
+          env
+        end
+
+        def raw(status, headers, body)
+          lines = [ "HTTP/1.1 #{status} #{reason(status)}" ]
+
+          headers.each do |name, value|
+            next if %w[content-length transfer-encoding].include?(name.to_s.downcase)
+
+            Array(value).flat_map { |held| held.to_s.split(/\r?\n/) }.each { |held| lines << "#{name}: #{held}" }
+          end
+
+          lines << "content-length: #{body.bytesize}"
+
+          "#{lines.join("\r\n")}\r\n\r\n".b + body
+        end
+
+        def parsed(request, raw)
+          io = Net::BufferedIO.new(StringIO.new(raw))
+          response = Net::HTTPResponse.read_new(io)
+          response.uri = request.uri
+          response.reading_body(io, request.response_body_permitted?) { response.body }
+          response
+        end
+
+        def reason(status)
+          named = Net::HTTPResponse::CODE_TO_OBJ[status.to_s]
+
+          named ? named.name.delete_prefix("Net::HTTP").gsub(/(?<=[a-z])(?=[A-Z])/, " ") : "Unknown"
+        end
+    end
+  end
+end

data/lib/masks/client/enrollment.rb

@@ -0,0 +1,33 @@
+module Masks
+  module Client
+    class Enrollment
+      attr_reader :initial_access_token, :scope, :expires_in, :obtained_at
+
+      def self.issued(body)
+        if body["initial_access_token"].to_s.empty?
+          raise Rejected.new(
+            body["error"] || "invalid_enrollment_response",
+            body["error_description"] || "the enrollment endpoint answered without an initial_access_token"
+          )
+        end
+
+        new(body)
+      end
+
+      def initialize(body)
+        @initial_access_token = body["initial_access_token"]
+        @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 scopes
+        scope.split
+      end
+    end
+  end
+end

data/lib/masks/client/errors.rb

@@ -4,6 +4,12 @@ module Masks
 
     class Unreachable < Error; end
 
+    class Foreign < Error; end
+
+    class Insecure < Error; end
+
+    class ReplayUnavailable < Error; end
+
     class Rejected < Error
       attr_reader :code, :description, :status
 

data/lib/masks/client/http.rb

@@ -3,6 +3,7 @@ module Masks
     module HTTP
       OPEN_TIMEOUT = 5
       READ_TIMEOUT = 10
+      READ_LIMIT = 1 << 20
 
       module_function
 
@@ -11,12 +12,22 @@ module Masks
       end
 
       def post_form(url, form, headers = {})
-        uri = URI.parse(url.to_s)
-        request = Net::HTTP::Post.new(uri, default_headers.merge(headers))
+        encoded(Net::HTTP::Post, url, form, headers)
+      end
+
+      def delete_form(url, form, headers = {})
+        encoded(Net::HTTP::Delete, url, form, headers)
+      end
+
+      def encoded(verb, url, form, headers)
+        request(form_request(verb, url, form, headers))
+      end
+
+      def form_request(verb, url, form, headers)
+        request = verb.new(URI.parse(url.to_s), default_headers.merge(headers))
         request.body = URI.encode_www_form(form)
         request["Content-Type"] = "application/x-www-form-urlencoded"
-
-        self.request(request)
+        request
       end
 
       def post_json(url, body, headers = {})
@@ -32,7 +43,10 @@ module Masks
       end
 
       def fetch(url, headers = {})
-        uri = URI.parse(url.to_s)
+        uri = checked(URI.parse(url.to_s))
+        embedded = Masks::Client.embedded_for(uri)
+
+        return embedded.deliver(Net::HTTP::Get.new(uri, headers)) if embedded
 
         Net::HTTP.start(
           uri.hostname, uri.port,
@@ -58,26 +72,62 @@ module Masks
       end
 
       def request(request)
-        uri = request.uri
+        parse(deliver(request))
+      end
+
+      def deliver(request, limit: READ_LIMIT)
+        uri = checked(request.uri)
+        embedded = Masks::Client.embedded_for(uri)
 
-        response = Net::HTTP.start(
+        return embedded.deliver(request, limit: limit) if embedded
+
+        Net::HTTP.start(
           uri.hostname, uri.port,
           use_ssl: uri.scheme == "https",
           open_timeout: OPEN_TIMEOUT,
           read_timeout: READ_TIMEOUT
-        ) { |http| http.request(request) }
-
-        parse(response)
+        ) { |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})"
       end
 
-      def parse(response)
-        body = begin
-          JSON.parse(response.body.to_s)
-        rescue JSON::ParserError
-          {}
+      def checked(uri)
+        return uri if uri.is_a?(URI::HTTPS) && !uri.host.to_s.empty?
+        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"
+        end
+
+        raise Error, "#{uri} is not an http or https URL"
+      end
+
+      def loopback?(host)
+        name = host.to_s.downcase
+
+        return true if name == "localhost" || name.end_with?(".localhost")
+
+        IPAddr.new(name).loopback?
+      rescue IPAddr::Error
+        false
+      end
+
+      def limited(http, request, limit)
+        http.request(request) do |response|
+          body = +""
+
+          response.read_body do |chunk|
+            body << chunk
+            raise Error, "#{request.uri.host} answered with more than #{limit} bytes" if body.bytesize > limit
+          end
+
+          response.body = body
         end
+      end
+
+      def parse(response)
+        body = decoded(response)
 
         unless response.is_a?(Net::HTTPSuccess)
           refusal = Unregistered.raised_by?(body) ? Unregistered : Rejected
@@ -91,6 +141,30 @@ module Masks
 
         body
       end
+
+      def decoded(response)
+        raw = response.body.to_s
+        return {} if raw.strip.empty?
+
+        held = JSON.parse(raw)
+
+        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)
+      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)
+      end
+
+      def origin(response)
+        uri = response.uri
+
+        uri ? Nonces.origin(uri) : "the server"
+      end
     end
   end
 end

data/lib/masks/client/issuer.rb

@@ -14,13 +14,14 @@ module Masks
         Masks::Client.registry[issuer, ttl: ttl]
       end
 
-      attr_reader :url
+      attr_reader :url, :nonces
 
       def initialize(url, ttl: TTL)
         @url = self.class.normalize(url)
         @ttl = ttl
         @cache = {}
         @lock = Mutex.new
+        @nonces = Nonces.new
       end
 
       def discovery