masks 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fab2f5044bc29a407688ac0c61ac703108849a24579a7aa2e30e18234d6e02f0
-  data.tar.gz: 64572497372118a8ac2677634c26349c53cf93e4850188ceecaa2e2610d18546
+  metadata.gz: 5da19b0cb3099ebe46f2b4509615a75422fa0b2820abb799e8f182ce11f456ad
+  data.tar.gz: 4d5d6b573cccbca63439587cd3363d22be28dd0d8ff95051f32dcc8252494185
 SHA512:
-  metadata.gz: ea4c88b70e03f9feb1a98886c1a04ae0f913f4c5a7de609b95215b12901b7530d9017d2f154c21c5893e7a10282e3bf8cd7ca005a068bab0aac1fe9b45139440
-  data.tar.gz: d4c0af7c25dbc3bc380b4793f82c5c172a4bfe3b2bff150310e4b9689d1e9c7f07a0be1833cd406c16dec0fce60f30032b95b4466dc93bd46059b0714ec0096d
+  metadata.gz: 130ccd4e8a1ca7ddfe996f7439af4dc800501ea0a81ec0a18561475447931af40affb0cd0e2a66aa191d28d93f677046f49b7d5db6a913426fa21114d1bcbb68
+  data.tar.gz: bd818590edc19a344daf59e755d8657da71e10f2017fc3b8ffe95ed6f8452f804a6ccdc7da621425b288c5934b25b5c39bd41923d13983e16fab9ab144bdfd78

data/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## [0.7.0](https://github.com/masksrb/masks/compare/gem/v0.6.0...gem/v0.7.0) (2026-09-13)
+
+
+### ⚠ BREAKING CHANGES
+
+* **client:** Masks::Client::Introspection#username is now #nickname.
+
+### Features
+
+* **client:** an app can act on a logout the issuer tells it about ([4d0b7f7](https://github.com/masksrb/masks/commit/4d0b7f77a74b0e416dda3e90413ad989a909f344))
+* **client:** an app that delegates asks its handshake for masks:delegate: and the token exchange ([912e856](https://github.com/masksrb/masks/commit/912e856b00a9f27d59af861cdb35da518fa862bc))
+* **client:** an app that delegates registers where connecting a person's account comes back to ([738fba6](https://github.com/masksrb/masks/commit/738fba67e544f7c8a9a15cd55befbd66696b707b))
+* **client:** an unconnected app walks straight into the handshake ([040388e](https://github.com/masksrb/masks/commit/040388e188653f67ef7a59bc0aa9aef02ec351b2))
+* **server:** an application is let use somebody's account elsewhere through a delegation ([4b7048c](https://github.com/masksrb/masks/commit/4b7048cb8ac4e174b9359a070b7a2d942a1c410d))
+
+
+### Fixes
+
+* **client:** back-channel logout says 501 when the app does nothing about it ([60e1125](https://github.com/masksrb/masks/commit/60e1125c02adec7c822c6d3757210e825bb66cfc))
+
+
+### Documentation
+
+* hold the copyright as the masks authors ([cffdeb5](https://github.com/masksrb/masks/commit/cffdeb59f14eb02f6a9513d5f7cda21ebaee2171))
+* READMEs that match the code, and a server one that is not the scaffold ([e0148e1](https://github.com/masksrb/masks/commit/e0148e14e0092731bcd095bc0fc22a1589c3acc0))
+* references are generated from the code that defines them ([ba74550](https://github.com/masksrb/masks/commit/ba745501e651b797948e5abd5640a1825616100c))
+* the gem reference survives rdoc 8, and lists what a Concern adds ([36df12e](https://github.com/masksrb/masks/commit/36df12e72cc52f5db650d16778ecc501bf9db14a))
+* the rose window is the site's logo, favicon and hero, and heads every README ([72176e4](https://github.com/masksrb/masks/commit/72176e49c81bc0a5d6730f3b9e5eaa693db8a659))
+
+
+### Refactoring
+
+* **client:** an introspection answers a nickname, not a username ([f23dff5](https://github.com/masksrb/masks/commit/f23dff537320982d42a8e4823bea784a3d80ec33))
+* comments are gone; the code says what it does ([0fc8e6a](https://github.com/masksrb/masks/commit/0fc8e6a4692e3f09831514b6d167c3e23d7db419))
+* every suite is named for what it proves, under one test directory ([315b371](https://github.com/masksrb/masks/commit/315b371e64baa4441014669744a61c88341d27c7))
+* rename the example tenant from jons to demo ([aef32a6](https://github.com/masksrb/masks/commit/aef32a670b4b3c696089c07bf15103e1d981eb00))
+* **server:** delegation shares what sign-in and linking already had, and asks the database less ([44b8c4d](https://github.com/masksrb/masks/commit/44b8c4d303dfcc6de60f98d7824c544bd67e347c))
+* take the owner's domain out of the boundary check ([df580ee](https://github.com/masksrb/masks/commit/df580ee1fb5820d30a57a88f3aa9825c97682725))
+
+## [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/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 geiger.to
+Copyright (c) 2026 the masks authors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,3 +1,5 @@
+<p align="center"><img src="https://raw.githubusercontent.com/masksrb/masks/main/server/public/icon.svg" width="120" alt="The masks rose window"></p>
+
 # masks
 
 Sign a Ruby or Rails app in against a [masks](https://github.com/masksrb/masks) issuer.
@@ -7,9 +9,9 @@ gem "masks"
 ```
 
 Three parts, in one gem. **Consumers spend tokens. Resource servers accept them.** Most
-client libraries only build the first, so everything above the second gets written by
-hand in each resource server — its scope check, its `WWW-Authenticate` header, its
-metadata document. Both halves are here, and a Rails engine that mounts them.
+client libraries build only the first, leaving each resource server to write its own
+scope check, its `WWW-Authenticate` header and its metadata document. Both halves are
+here, with a Rails engine that mounts them.
 
 The engine loads only when Rails does. A Sinatra, Hanami or plain-Rack app requiring
 this gem pulls in `jwt` and nothing else.
@@ -29,12 +31,16 @@ the file credentials land in. Set `MASKS_ISSUER`, start the app, and open
 
 ### The handshake
 
-A first-party app must not self-register anonymously — that is how a stranger's
-connector also arrives. So an unconnected app is offered one button, the browser goes to
-its own issuer's approval screen, and the one-time token that comes back is redeemed
+A first-party app must not self-register anonymously, since that is also how a
+stranger's connector arrives. An unconnected app sends the browser straight on to its
+own issuer's approval screen, and the one-time token that comes back is redeemed
 server-side. **The secret never travels through the browser and nobody types it
 anywhere.**
 
+The only thing `/auth/handshake` stops a browser to say is that the app is configured
+too little to shake hands at all, or that the issuer refused. A connected app asks
+before it rotates, since reconnecting takes it offline for a moment.
+
 The engine writes what comes back to `config/masks.json`, mode 600. An app that wants
 somewhere else says so:
 
@@ -48,7 +54,7 @@ Those two lambdas are the whole integration for a multi-tenant app.
 ### Signing in
 
 ```ruby
-class ThingsController < ApplicationController
+class UrisController < ApplicationController
   include Masks::Rails::Authentication
 
   before_action :authenticate_masks!
@@ -60,7 +66,7 @@ end
 ```
 
 `masks_identity`, `masks_tenant` and `masks_scopes` are what a signed-in request carries.
-Tokens live in the encrypted Rails session and never reach JavaScript — this is the
+Tokens live in the encrypted Rails session and never reach JavaScript. This is the
 backend-for-frontend pattern, and it is the default because an SPA holding a token is an
 SPA where XSS lifts one.
 
@@ -70,7 +76,7 @@ controller if that is what you want; otherwise include it where you mean it.
 ### An SPA in front of it
 
 `GET /auth/session` answers identity, tenant and scopes as JSON, or `401` with somewhere
-to send the browser. [`@masks/client`](../web) speaks it:
+to send the browser. [`@masks/client`](https://masks.pages.dev/reference/browser/) speaks it:
 
 ```js
 import { createSession } from "@masks/client"
@@ -79,10 +85,9 @@ const session = createSession()
 const status = await session.status()
 ```
 
-`status()` answers one of three things, and the third is why it exists: `signed_in`,
-`signed_out` with where to sign in, and `handshake_required` with where to go instead —
-because an app nobody has connected must not offer a sign-in button that leads to an
-error page at the issuer.
+`status()` answers one of three states: `signed_in`, `signed_out` with where to sign in,
+and `handshake_required` with where to go instead. The third exists because an app nobody
+has connected must not offer a sign-in button that leads to an error page at the issuer.
 
 ### Accepting tokens
 
@@ -92,14 +97,37 @@ An app that is also a resource server:
 class ApiController < ApplicationController
   include Masks::Rails::ProtectedResource
 
-  before_action { masks_protect!(scope: "things:read") }
+  masks_protect! scope: "uris:catalog:read"
 end
 ```
 
+`masks_protect!` is a class method that installs the `before_action` itself, and passes `:only` and
+`:except` through.
+
 `masks_claims` is the verified token. A refusal carries the RFC 6750 challenge with
 `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
@@ -135,7 +163,7 @@ holds no protocol of its own.
 
 ```ruby
 session = Masks::Client::Session.new(
-  issuer: "https://jons.auth.example.com",
+  issuer: "https://demo.auth.example.com",
   client_id: id, client_secret: secret,
   redirect_uri: "https://app.example.com/auth/callback"
 )
@@ -149,8 +177,7 @@ identity = session.identity(tokens)
 ```
 
 `start` sends a nonce only when `openid` was asked for, so holding one means an id token
-is owed — which is what lets the check on the way back be exact rather than vacuously
-true.
+is owed, and the check on the way back is exact.
 
 Also: `refresh`, `exchange`, `revoke`, `introspect`, `userinfo`, and `end_session_url`.
 
@@ -161,12 +188,11 @@ constructing one per request.
 
 ### The handshake
 
-The flow that connects a first-party app, rather than two helpers and sixty lines of
-state in every consumer:
+The flow that connects a first-party app:
 
 ```ruby
 handshake = Masks::Client::Handshake.new(
-  issuer, name: "things", resource: "https://app.example.com/mcp",
+  issuer, name: "uris", resource: "https://app.example.com/mcp",
   redirect_uris: [ "https://app.example.com/auth/callback" ],
   return_to: "https://app.example.com/"
 )
@@ -182,12 +208,12 @@ that is not the issuer it asked — each **before** anything is redeemed.
 
 ```ruby
 resource = Masks::Client::Resource.new(
-  issuer: "https://jons.auth.example.com",
+  issuer: "https://demo.auth.example.com",
   url: "https://app.example.com/mcp",
-  scopes: { "things:read" => "Search your catalog" }
+  scopes: { "uris:catalog:read" => "Search your catalog" }
 )
 
-claims = resource.authenticate(request.authorization, scope: "things:read")
+claims = resource.authenticate(request.authorization, scope: "uris:catalog:read")
 claims.subject
 claims.tenant.subdomain
 ```
@@ -201,35 +227,87 @@ response.headers["WWW-Authenticate"] = resource.challenge(error)
 
 `resource.metadata` is the RFC 9728 document to serve at
 `/.well-known/oauth-protected-resource`. The `scope_descriptions` extension in it is how
-an auth server renders your scopes as sentences on its consent screen — it has no other
-way to know what `things:read` means.
+an auth server renders your scopes as sentences on its consent screen; it has no other
+way to know what `uris:catalog:read` means.
 
 There is a Rack middleware for consumers that want the challenge below the framework:
 
 ```ruby
-use Masks::Client::Rack, resource: resource, scope: "things:read"
+use Masks::Client::Rack, resource: resource, scope: "uris:catalog:read"
 ```
 
 ### Introspection
 
 A resource server doing JWT-only validation cannot see a revocation until the token
-expires. Asking is the honest answer:
+expires. Ask the issuer instead:
 
 ```ruby
 found = session.introspect(token)
-found.active? && found.permits?("things:read")
+found.active? && found.permits?("uris:catalog:read")
 ```
 
 `Introspection` is a `Claims` whose `permit!` raises when the issuer says the token is
-not active, so switching from local verification to asking does not mean remembering to
-check a boolean.
+not active, so moving from local verification to introspection needs no extra boolean
+check.
+
+### Somebody else's account
+
+An app that acts as somebody at Google, Microsoft or an MCP server while they are away asks masks for
+a [delegation](https://masks.pages.dev/concepts/delegation/). masks keeps and refreshes the
+provider's tokens; the app keeps one secret per connection and trades it for a live access token when
+the last one runs out.
+
+```ruby
+delegations = Masks::Client.delegations(
+  ENV["MASKS_ISSUER"], client_id: id, client_secret: secret, redirect_uri: "https://app.test/connect/callback"
+)
+
+started = delegations.start(provider: "google")
+session[:connecting] = started
+redirect_to started["url"]
+
+held = delegations.finish(params: params, started: session.delete(:connecting))
+held.connection
+held.secret
+
+upstream = delegations.token(held.secret, connection: held.connection)
+upstream.access_token
+upstream.expires_at
+upstream.secret
+```
+
+A Rails app sets `config.delegates = true`, so its handshake asks for `masks:delegate:` and the token
+exchange with it.
+
+`upstream.secret` replaces the one you passed in, every time. `Delegations::Refused` means somebody
+has to connect again; `Delegations::Unavailable` is worth retrying. Both carry `secret` when masks had
+already rotated it, so keep it. Spend a secret from one place at a time: spending one twice revokes
+it.
+
+Tests use the fake, which needs no issuer:
+
+```ruby
+require "masks/client/delegations/fake"
+
+fake = Masks::Client::Delegations::Fake.new
+started = fake.start(provider: "notion")
+held = fake.finish(params: fake.approve(started), started: started)
+
+fake.token(held.secret, connection: held.connection)
+fake.revoke(held.connection)
+fake.unavailable(held.connection)
+```
 
 ## Which issuers this speaks to
 
 masks publishes `masks_protocol_version` in its discovery document, and this gem needs at
 least version 1 — the one that serves `handshake_endpoint` and the approval flow behind
-it. An older issuer is refused with a sentence saying so, rather than at the first screen
-anybody touches.
+it. An older issuer is refused at configuration time, with a sentence saying so.
+
+## Documentation
+
+This README is the reference for the gem. [masks.pages.dev](https://masks.pages.dev) carries what is
+generated from the server's own code — the `/manage` GraphQL schema, and the design system.
 
 ## License
 

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

@@ -4,17 +4,13 @@ module Masks
       before_action :require_unconfigured_or_signed_in
 
       def show
-        @connected = masks_config.configured?(request)
-        @can_disconnect = @connected && masks_config.can_forget?
+        return begin! unless masks_config.configured?(request)
+
+        @can_disconnect = masks_config.can_forget?
       end
 
       def create
-        pending = masks_handshakes.open
-        started = masks_config.handshake_for(request).start(state: pending.id)
-
-        redirect_to started[:url], allow_other_host: true
-      rescue Masks::Client::Error => e
-        refuse(e)
+        begin!
       end
 
       def callback
@@ -31,15 +27,11 @@ module Masks
         refuse(e)
       end
 
-      # Rotating is what masks does with a second run — the client is keyed on
-      # the resource identifier, so approving again replaces the credentials
-      # rather than leaving a tenant with two and no way to tell which one the
-      # browser holds. Disconnecting is the other half, and it is RFC 7592.
       def destroy
         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 +43,19 @@ module Masks
 
       private
 
-        def masks_registration
-          Masks::Client::Registration.held(
-            masks_config.issuer_for(request),
-            masks_config.credentials_for(request)
-          )
+        def begin!
+          pending = masks_handshakes.open
+          started = masks_config.handshake_for(request).start(state: pending.id)
+
+          redirect_to started[:url], allow_other_host: true
+        rescue Masks::Client::Error => e
+          refuse(e)
+        end
+
+        def forget_upstream
+          masks_registration&.delete
+        rescue Masks::Client::Unregistered
+          false
         end
 
         def returned

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

@@ -0,0 +1,32 @@
+module Masks
+  module Rails
+    class LogoutsController < BaseController
+      skip_forgery_protection
+
+      def create
+        return refuse("invalid_request", "logout_token is required") if params[:logout_token].blank?
+
+        logout = masks_session.logout_token(params[:logout_token])
+
+        heard = masks_config.logged_out!(request, logout)
+
+        response.headers["Cache-Control"] = "no-store"
+
+        head(heard ? :ok : :not_implemented)
+      rescue Masks::Client::InvalidToken => e
+        refuse("invalid_request", e.message)
+      rescue Masks::Rails::Configuration::Unconfigured => e
+        refuse("invalid_request", e.message)
+      end
+
+      private
+
+        def refuse(code, description)
+          response.headers["Cache-Control"] = "no-store"
+
+          render json: { "error" => code, "error_description" => description },
+                 status: :bad_request
+        end
+    end
+  end
+end

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/app/views/masks/rails/handshakes/show.html.erb

@@ -1,40 +1,24 @@
-<% if @connected %>
-  <% content_for :title, "Reconnect this app" %>
+<% content_for :title, "Reconnect this app" %>
 
-  <h1>This app is connected</h1>
+<h1>This app is connected</h1>
 
-  <p class="muted">
-    Reconnecting replaces the credentials it holds now with a fresh pair. It is
-    how you rotate them, and it is the only way to move this app to a different
-    account. Nothing is typed in and no secret travels through your browser.
-  </p>
+<p class="muted">
+  Reconnecting replaces the credentials it holds now with a fresh pair. It is
+  how you rotate them, and it is the only way to move this app to a different
+  account. Nothing is typed in and no secret travels through your browser.
+</p>
 
-  <p class="muted">
-    It will stop working between the approval and the moment it picks the new
-    credentials up.
-  </p>
+<p class="muted">
+  It will stop working between the approval and the moment it picks the new
+  credentials up.
+</p>
 
-  <%= form_with url: handshake_path, method: :post do %>
-    <button type="submit">Reconnect it</button>
-  <% end %>
-
-  <% if @can_disconnect %>
-    <%= form_with url: handshake_path, method: :delete do %>
-      <button type="submit">Disconnect it</button>
-    <% end %>
-  <% end %>
-<% else %>
-  <% content_for :title, "Connect this app" %>
-
-  <h1>This app has not been connected yet</h1>
-
-  <p class="muted">
-    Nobody can sign in here until it holds credentials from the server that signs
-    people in. Getting them takes one approval, from whoever owns this tenant —
-    nothing is typed in, and no secret travels through your browser.
-  </p>
+<%= form_with url: handshake_path, method: :post do %>
+  <button type="submit">Reconnect it</button>
+<% end %>
 
-  <%= form_with url: handshake_path, method: :post do %>
-    <button type="submit">Connect it</button>
+<% if @can_disconnect %>
+  <%= form_with url: handshake_path, method: :delete do %>
+    <button type="submit">Disconnect it</button>
   <% end %>
 <% end %>

data/config/routes.rb

@@ -1,8 +1,10 @@
 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
+  post "/logout/backchannel", to: "logouts#create", as: :backchannel_logout
 
   get "/handshake", to: "handshakes#show", as: :handshake
   post "/handshake", to: "handshakes#create"

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