masks 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fab2f5044bc29a407688ac0c61ac703108849a24579a7aa2e30e18234d6e02f0
-  data.tar.gz: 64572497372118a8ac2677634c26349c53cf93e4850188ceecaa2e2610d18546
+  metadata.gz: d4455d2e731a770253802292bce1dd21a9b97c05489e65ba4a1f310c24873b79
+  data.tar.gz: df05e39f40a1f08fbb77897549c584653bf17676c3e6b13b64220e1751360e64
 SHA512:
-  metadata.gz: ea4c88b70e03f9feb1a98886c1a04ae0f913f4c5a7de609b95215b12901b7530d9017d2f154c21c5893e7a10282e3bf8cd7ca005a068bab0aac1fe9b45139440
-  data.tar.gz: d4c0af7c25dbc3bc380b4793f82c5c172a4bfe3b2bff150310e4b9689d1e9c7f07a0be1833cd406c16dec0fce60f30032b95b4466dc93bd46059b0714ec0096d
+  metadata.gz: 39e55aecad7e80a3cef669b9bcbe16f6f942c326bf98a9f9da954663365740d9e31a814a3da644ef68bd0090f040f853ff4b3bdda34f2f8fe6dd4b749190d138
+  data.tar.gz: 4cca8c0d431151c0a0865969dcc38767388ec4f93c1ab5e2b824e7dd875f8a38135969d7b8ed5a1966eb9b0f51b3fb60e8cff887c67d180561b3474e47653d84

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.6.0](https://github.com/masksrb/masks/compare/gem-v0.5.0...gem/v0.6.0) (2026-09-05)
+
+
+### Features
+
+* **server:** a namespace is a grant, so an app can grow its own scopes ([4e816e4](https://github.com/masksrb/masks/commit/4e816e4456de9cc05601b8eaa03773788e3178bb))
+* **server:** people, avatars, and one page instead of three ([d50c444](https://github.com/masksrb/masks/commit/d50c4440812fc1c3a92e926ff6d533b9a69dae2a))
+
+
+### Fixes
+
+* **client:** an app whose issuer forgot it asks to be reconnected ([6956972](https://github.com/masksrb/masks/commit/695697233ca1ce35fa8b29ea74e58dd0d762b0a5))
+
 ## 0.5.0 — unreleased
 
 First release carrying the consumer half in full. 0.4.0 predates the split described in

data/README.md

@@ -100,6 +100,26 @@ end
 `resource_metadata`, so a client handed nothing but a URL can find its way to the issuer
 and back.
 
+### Avatars
+
+Every actor has three faces at once — an uploaded `photo`, an `identicon`, and two-letter
+`initials`. All three arrive on the id token, so drawing one costs no request.
+
+```erb
+<img src="<%= masks_claims.avatars.identicon %>?size=64" width="64" height="64" alt="">
+```
+
+A photo is a likeness of a person and needs a token, which an `<img>` cannot carry, so the engine
+proxies it with the token this app already holds:
+
+```erb
+<img src="/auth/avatar" width="64" height="64" alt="">
+```
+
+`masks_claims.picture` resolves the standard OIDC claim — an offsite `picture_url` if the actor set
+one, then the photo, then the identicon. `issuer.avatar_url(sub, style:, size:)` builds a URL for a
+subject this app holds no token for. Sizes are 32, 64, 128, 256 or 512.
+
 ### Signing out
 
 `DELETE /auth/logout` ends this app's session. Add `?everywhere=1` and the response

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

@@ -0,0 +1,51 @@
+module Masks
+  module Rails
+    class AvatarsController < BaseController
+      SIZES = [ 32, 64, 128, 256, 512 ].freeze
+
+      def show
+        return head :not_found unless masks_signed_in?
+
+        url = photo_url
+
+        return head :not_found if url.nil?
+
+        deliver(
+          Masks::Client::HTTP.fetch(
+            url, "Authorization" => masks_tokens.authorization, "Accept" => "image/*"
+          )
+        )
+      rescue Masks::Client::Error
+        head :bad_gateway
+      end
+
+      private
+
+        def photo_url
+          held = masks_claims.avatars.photo
+
+          return nil if held.nil?
+          return nil unless held.start_with?("#{masks_config.issuer_for(request)}/")
+
+          asked = params[:size].presence
+
+          return held if asked.nil?
+
+          "#{held}?size=#{SIZES.find { |allowed| allowed >= asked.to_i } || SIZES.last}"
+        end
+
+        def deliver(answer)
+          case answer
+          when Net::HTTPRedirection
+            redirect_to answer["Location"], allow_other_host: true
+          when Net::HTTPSuccess
+            expires_in 5.minutes, public: false
+
+            send_data answer.body, type: answer["Content-Type"], disposition: "inline"
+          else
+            head :not_found
+          end
+        end
+    end
+  end
+end

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

@@ -39,7 +39,7 @@ module Masks
         return redirect_to(masks_config.after_sign_out) unless masks_signed_in?
         return redirect_to(masks_handshake_path) unless masks_config.can_forget?
 
-        masks_registration&.delete
+        forget_upstream
 
         masks_config.forget!(request)
         masks_forget
@@ -51,11 +51,10 @@ module Masks
 
       private
 
-        def masks_registration
-          Masks::Client::Registration.held(
-            masks_config.issuer_for(request),
-            masks_config.credentials_for(request)
-          )
+        def forget_upstream
+          masks_registration&.delete
+        rescue Masks::Client::Unregistered
+          false
         end
 
         def returned

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

@@ -14,6 +14,7 @@ module Masks
 
       def start
         return redirect_to(masks_handshake_path) unless masks_configured?
+        return redirect_to(masks_handshake_path) if masks_reconnect!
 
         pending = masks_requests.open(
           return_to: requested_return_to || session.delete(:masks_return_to)
@@ -55,6 +56,10 @@ module Masks
         masks_store(tokens, identity: identity)
 
         redirect_to pending[:return_to] || masks_config.after_sign_in
+      rescue Masks::Client::Unregistered => e
+        return redirect_to(masks_handshake_path) if masks_disconnect!
+
+        refuse(e.code, e.description, pending)
       rescue Masks::Client::Error => e
         refuse(e.class.name.demodulize.underscore, e.message, pending)
       end

data/config/routes.rb

@@ -1,6 +1,7 @@
 Masks::Rails::Engine.routes.draw do
   get "/", to: "sessions#start", as: :start
   get "/session", to: "sessions#show", as: :session
+  get "/avatar", to: "avatars#show", as: :avatar
   get "/callback", to: "sessions#callback", as: :callback
   match "/logout", to: "sessions#destroy", via: %i[get post delete], as: :logout
 

data/lib/masks/client/claims.rb

@@ -29,6 +29,39 @@ module Masks
         end
       end
 
+      class Avatars
+        STYLES = %w[photo identicon initials].freeze
+        FALLBACK = "identicon".freeze
+
+        attr_reader :to_h
+
+        def initialize(hash)
+          @to_h = hash.is_a?(Hash) ? hash : {}
+        end
+
+        STYLES.each do |style|
+          define_method(style) { to_h[style] }
+        end
+
+        def [](style)
+          to_h[style.to_s]
+        end
+
+        def photo?
+          !photo.nil?
+        end
+
+        def present?
+          to_h.any?
+        end
+
+        def ==(other)
+          other.is_a?(Avatars) ? to_h == other.to_h : false
+        end
+      end
+
+      AVATARS = "masks:avatars".freeze
+
       attr_reader :to_h
 
       def initialize(claims)
@@ -67,6 +100,14 @@ module Masks
         @tenant ||= Tenant.new(self["tenant"])
       end
 
+      def avatars
+        @avatars ||= Avatars.new(self[AVATARS])
+      end
+
+      def picture
+        self["picture"] || avatars.photo || avatars.identicon
+      end
+
       def scopes
         @scopes ||= self["scope"].to_s.split(/\s+/).reject(&:empty?).freeze
       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/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/issuer.rb

@@ -51,6 +51,22 @@ module Masks
         discovery.fetch(name) { raise Rejected.new("invalid_issuer", "#{url} publishes no #{name}") }
       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/registration.rb

@@ -59,18 +59,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 +98,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/rails/authentication.rb

@@ -6,7 +6,8 @@ module Masks
 
       included do
         if respond_to?(:helper_method)
-          helper_method :masks_signed_in?, :masks_identity, :masks_tenant, :masks_scopes
+          helper_method :masks_signed_in?, :masks_identity, :masks_tenant, :masks_scopes,
+                        :masks_claims
         end
       end
 
@@ -48,7 +49,10 @@ module Masks
         session[masks_config.session_key] || {}
       end
 
-      IDENTITY = %w[sub name preferred_username email email_verified tenant].freeze
+      IDENTITY = [
+        "sub", "name", "preferred_username", "email", "email_verified", "tenant",
+        "picture", Masks::Client::Claims::AVATARS
+      ].freeze
 
       def masks_identity_from(tokens)
         return nil if tokens.id_token.nil?
@@ -70,6 +74,36 @@ module Masks
         masks_config.configured?(request)
       end
 
+      def masks_registration
+        Masks::Client::Registration.held(
+          masks_config.issuer_for(request),
+          masks_config.credentials_for(request)
+        )
+      end
+
+      def masks_registered?
+        held = masks_registration
+
+        held.nil? || held.known?
+      rescue Masks::Client::Error
+        true
+      end
+
+      def masks_disconnect!
+        return false unless masks_configured? && masks_config.can_forget?
+
+        masks_config.forget!(request)
+        masks_forget
+
+        true
+      end
+
+      def masks_reconnect!
+        return false if masks_registered?
+
+        masks_disconnect!
+      end
+
       def masks_handshake_path
         Masks::Rails::Engine.routes.url_helpers.handshake_path
       end
@@ -84,6 +118,10 @@ module Masks
         masks_identity&.dig("tenant")
       end
 
+      def masks_claims
+        @masks_claims ||= Masks::Client::Claims.new(masks_identity || {})
+      end
+
       def masks_scopes
         masks_tokens&.scopes || []
       end
@@ -107,6 +145,9 @@ module Masks
           )
         )
         true
+      rescue Masks::Client::Unregistered
+        masks_disconnect!
+        false
       rescue Masks::Client::Rejected
         masks_forget
         false
@@ -144,6 +185,8 @@ module Masks
           "nickname" => identity["preferred_username"],
           "email" => identity["email"],
           "email_verified" => identity["email_verified"],
+          "picture" => masks_claims.picture,
+          "avatars" => masks_claims.avatars.to_h.presence,
           "tenant" => masks_tenant,
           "scopes" => masks_scopes,
           "expires_at" => masks_tokens&.expires_at

data/lib/masks/rails/configuration.rb

@@ -3,8 +3,8 @@ module Masks
     class Configuration
       class Unconfigured < Masks::Client::Error; end
 
-      attr_accessor :scope, :resource, :resource_scopes, :after_sign_in, :after_sign_out,
-                    :session_key, :sign_out_of_issuer, :parent_controller,
+      attr_accessor :scope, :namespace, :resource, :resource_scopes, :after_sign_in,
+                    :after_sign_out, :session_key, :sign_out_of_issuer, :parent_controller,
                     :credentials_path, :authenticate_everything
       attr_writer :issuer, :redirect_uri, :name, :credentials, :store, :forget
 
@@ -134,10 +134,22 @@ module Masks
             raise(Unconfigured, "Masks::Rails.config.resource is not set"),
           redirect_uris: [ redirect_uri_for(request) ],
           return_to: return_to_for(request),
-          scope: scope
+          scope: approved_scope
         )
       end
 
+      # What the handshake asks to be approved for, which is not what a sign-in
+      # requests. An app that owns a namespace asks for the namespace once, so
+      # that adding a capability later is a deployment rather than an approval
+      # round; the authorize request still names the scopes it actually wants.
+      def approved_scope
+        return scope if namespace.blank?
+
+        outside = Array(scope).reject { |name| name.to_s.start_with?(namespace) }
+
+        outside + [ namespace ]
+      end
+
       def return_to_for(request)
         uri = URI.parse(redirect_uri_for(request))
         port = ":#{uri.port}" unless uri.port == uri.default_port

data/lib/masks/version.rb

@@ -1,3 +1,3 @@
 module Masks
-  VERSION = "0.5.0".freeze
+  VERSION = "0.6.0".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: masks
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - geiger
@@ -33,6 +33,7 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- app/controllers/masks/rails/avatars_controller.rb
 - app/controllers/masks/rails/base_controller.rb
 - app/controllers/masks/rails/handshakes_controller.rb
 - app/controllers/masks/rails/sessions_controller.rb