masks 0.9.1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 62fc7998cf31199eaa81f63d82063e3e20ab995c74c782c675e91628df7dcee3
-  data.tar.gz: 6d83a9474d9289c375acfcacd6c5c4e45a66a92d22e1683abba9780de3c63d43
+  metadata.gz: c0b13e1f370033e4c4512becb39b4d96e4b9d28b39b7f1e773592138626d1151
+  data.tar.gz: 8540eeecb1b448047198d5da57e5978d0e4ec249138334e7c39d41a719854a99
 SHA512:
-  metadata.gz: 97164bf9ab0ee6820e353a9dad5d97141ddf0cd038dd3a6348e03e46eea46313643e13f8d49c17bd414c16420e4b25c5c29072bd4efea114f3483e4174c0e599
-  data.tar.gz: 505cca23a8b1b0f439365eea100780b64157700ab9995df53fa46df640a0efc1da9a64e95281925279233ea4e4036563e41aebd727d8b7f2795991dac3604931
+  metadata.gz: fc1b4981446fdc5282e21c00c93a63cbc124d3c675512172a849cdd698f0a52839fce8098fdde6443814131f198eef5829d1dd52416e02bb51ef95f7d5fb634a
+  data.tar.gz: e40f6519f1c22fefa134217cff31701617551feed13e374f1d801307c2f021cb21eba5b85adc4eb9d28e133e855c4aad4cc05caa4749d34fadd9d7e833493cc1

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [0.10.0](https://github.com/masksrb/masks/compare/gem/v0.9.2...gem/v0.10.0) (2026-10-11)
+
+
+### Features
+
+* **client:** a sign-in can ask for a step-up scope the app offers, and masks grants it only to people whose scopes cover it ([84b43d8](https://github.com/masksrb/masks/commit/84b43d8c091440a5a9b75721b56f9ced27c9f82f))
+* **client:** masked is the signed-in person in one object, read the same way from a session or a bearer token ([c2ad60c](https://github.com/masksrb/masks/commit/c2ad60cb5d2c795f2bf711e8650af5e1893aa0d2))
+* **client:** masks_require_scope! guards an action with a step-up scope, sending its holder through masks once and refusing everyone else ([fce327e](https://github.com/masksrb/masks/commit/fce327edae9d6166e8bc163d85c4ca8e6548e1eb))
+* **client:** privileges name what an action needs, and masked! checks them for a browser session or a bearer token alike ([97e998a](https://github.com/masksrb/masks/commit/97e998a68bf3365fc5ba72a99ca21cf66c6e500a))
+
+## [0.9.2](https://github.com/masksrb/masks/compare/gem/v0.9.1...gem/v0.9.2) (2026-10-10)
+
+
+### Documentation
+
+* the examples name xixo, the resource server once called uris ([ca80f20](https://github.com/masksrb/masks/commit/ca80f20c9aea4ee6a3e7cd6c76c69425e4c800e3))
+
 ## [0.9.1](https://github.com/masksrb/masks/compare/gem/v0.9.0...gem/v0.9.1) (2026-10-04)
 
 

data/README.md

@@ -33,11 +33,12 @@ client secret never passes through the browser. The handshake registers the app
 asks before it rotates, because reconnecting takes it offline for a moment.
 
 Once an app is connected, only somebody `config.manages` approves can reconnect or disconnect it.
-The callable takes the request, or the request and the signed-in identity, and the engine refuses
-everyone when it is unset:
+It names a [privilege](#privileges), or is a callable taking the request, or the request and
+`masked`. The engine refuses everyone when it is unset:
 
 ```ruby
-config.manages = ->(request, identity) { identity["sub"] == ENV["OWNER_SUB"] }
+config.manages = :admin
+config.manages = ->(request, masked) { masked.subject == ENV["OWNER_SUB"] }
 ```
 
 The engine writes what comes back to `config/masks.json`, mode 600. A multi-tenant app keeps it
@@ -54,16 +55,46 @@ config.store = ->(request, registration) { Tenant.for(request).connect!(registra
 class DashboardController < ApplicationController
   include Masks::Rails::Authentication
 
-  before_action :authenticate_masks!
+  masked!
 
   def index
-    @who = masks_identity
+    @who = masked.name
   end
 end
 ```
 
-`masks_identity`, `masks_tenant`, and `masks_scopes` describe the signed-in request. Tokens live in
-the encrypted Rails session and never reach JavaScript.
+`masked` is everything about the signed-in request in one object: `subject`, `name`, `nickname`,
+`email`, `picture`, `avatars`, `tenant`, `organization`, `organizations`, `role?`, `scopes`,
+`privileges`, `privilege?`, `access_token`, and `signed_in?`, with `masked["claim"]` for any other
+claim. In a view it is the same helper. Tokens live in the encrypted Rails session and never reach
+JavaScript.
+
+### Privileges
+
+A privilege names what an action needs: scopes the person holds in masks, a role in the organization
+they signed in to, or both. A list is shorthand for `{ scope: [...] }`.
+
+```ruby
+Masks::Rails.configure do |config|
+  config.privileges = {
+    admin: %w[catalog:admin],
+    billing: { role: %w[owner billing] },
+    acme_admin: { scope: %w[catalog:admin], role: "owner", organization: "acme" }
+  }
+end
+
+class SettingsController < ApplicationController
+  masked!
+  masked! :admin, only: %i[create update destroy]
+end
+```
+
+`masked!` with no privilege needs only a sign-in. A privilege's scopes stay out of every ordinary
+sign-in. When a signed-in person lacks one, the browser goes through masks once to ask for it and
+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).
 
 `config.authenticate_everything = true` includes `Authentication` on every controller. Otherwise
 include it where it applies.
@@ -91,7 +122,7 @@ An app that is also a resource server:
 class ApiController < ApplicationController
   include Masks::Rails::ProtectedResource
 
-  masks_protect! scope: "uris:catalog:read", except: :metadata
+  masked! :read, except: :metadata
 
   def metadata
     render json: masks_resource_metadata
@@ -99,8 +130,8 @@ class ApiController < ApplicationController
 end
 ```
 
-`masks_protect!` installs the `before_action` and passes `:only` and `:except` through.
-`masks_claims` is the verified token. A refusal carries the RFC 6750 challenge with
+`masked!` checks a [privilege](#privileges) against the bearer token, here
+`config.privileges = { read: %w[xixo:catalog:read] }`. `masked` reads the verified token. A refusal carries the RFC 6750 challenge with
 `resource_metadata`, which points a client at `/.well-known/oauth-protected-resource`. The engine
 does not route that path, so route it to an action like `metadata` above. A DPoP-bound token is
 accepted only with a valid proof, as in [Masks::Client::Resource](#the-resource-server-half).
@@ -120,32 +151,28 @@ end
 class BillingController < ApplicationController
   include Masks::Rails::Authentication
 
-  masks_members_only! role: %w[owner billing]
+  masked! :billing
 end
 ```
 
-`masks_organization` is the organization signed in to (its `id`, `key`, `name`, and `role`), or
-`nil`, and `masks_role?("owner")` asks about the role held in it. A refresh reads the person's
+`masked.organization` is the organization signed in to (its `id`, `key`, `name`, and `role`), or
+`nil`, and `masked.role?("owner")` asks about the role held in it. A refresh reads the person's
 profile again, so a promotion or demotion reaches the app within an access token's lifetime.
 `/auth/session` answers the same thing as `organization`.
 
-`masks_organizations` lists every organization the person has joined, each with the role held in
+`masked.organizations` lists every organization the person has joined, each with the role held in
 it, and `/auth/session` answers it as `organizations`. Switching sends the person through sign-in
 again naming the other one, which asks nothing more when they are already a member:
 
 ```erb
-<% masks_organizations.each do |held| %>
+<% masked.organizations.each do |held| %>
   <%= link_to held.name, masks_login_url(organization: held.key, return_to: request.path) %>
 <% end %>
 ```
 
-`masks_members_only!` refuses with 403, as `insufficient_organization` when the person signed
-in to none and `insufficient_role` when they hold another role. A resource server asks the same of a
-token:
-
-```ruby
-masks_protect! scope: "uris:catalog:write", role: "owner", organization: "acme"
-```
+A privilege with a role refuses with 403, as `insufficient_organization` when the person signed in
+to none and `insufficient_role` when they hold another role. A resource server asks the same of a
+token with `masked!`.
 
 Naming an organization without asking for the scope still holds the sign-in to its members and its
 sign-in policy, and the app learns nothing about the role.
@@ -156,7 +183,7 @@ Every account has three avatars: an uploaded `photo`, an `identicon`, and two-le
 All three arrive on the ID token.
 
 ```erb
-<img src="<%= masks_claims.avatars.identicon %>?size=64" width="64" height="64" alt="">
+<img src="<%= masked.avatars.identicon %>?size=64" width="64" height="64" alt="">
 ```
 
 A photo needs a token, which an `<img>` cannot carry, so the engine proxies it with the token the
@@ -166,7 +193,7 @@ app holds:
 <img src="/auth/avatar" width="64" height="64" alt="">
 ```
 
-`masks_claims.picture` is the standard OIDC `picture` claim when the account set one, then the photo,
+`masked.picture` is the standard OIDC `picture` claim when the account 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.
 
@@ -187,6 +214,7 @@ a subdomain-per-tenant host needs.
 | `resource` | this app's own identifier, which the handshake registers and tokens name as their audience |
 | `resource_scopes` | what it accepts, published in its RFC 9728 metadata |
 | `scope` | what to ask the issuer for, `openid profile email` by default |
+| `privileges` | named scopes, roles, and organizations that `masked!` checks, none by default |
 | `organization` | the organization every sign-in names, by key |
 | `credentials` / `store` | where the handshake's result lives |
 | `manages` | who may reconnect or disconnect a connected app |
@@ -235,7 +263,7 @@ The flow that connects a first-party app:
 
 ```ruby
 handshake = Masks::Client::Handshake.new(
-  issuer, name: "uris", resource: "https://app.example.com/mcp",
+  issuer, name: "xixo", resource: "https://app.example.com/mcp",
   redirect_uris: [ "https://app.example.com/auth/callback" ],
   return_to: "https://app.example.com/"
 )
@@ -254,11 +282,11 @@ the issuer it asked.
 resource = Masks::Client::Resource.new(
   issuer: "https://demo.auth.example.com",
   url: "https://app.example.com/mcp",
-  scopes: { "uris:catalog:read" => "Search your catalog" }
+  scopes: { "xixo:catalog:read" => "Search your catalog" }
 )
 
 claims = resource.authenticate(
-  request.authorization, scope: "uris:catalog:read",
+  request.authorization, scope: "xixo:catalog:read",
   proof: request.get_header("HTTP_DPOP"), method: request.request_method, url: request.url
 )
 claims.subject
@@ -286,7 +314,7 @@ scope.
 A Rack middleware does the same below the framework, proof included:
 
 ```ruby
-use Masks::Client::Rack, resource: resource, scope: "uris:catalog:read"
+use Masks::Client::Rack, resource: resource, scope: "xixo:catalog:read"
 ```
 
 ### Introspection
@@ -296,7 +324,7 @@ asks the issuer:
 
 ```ruby
 found = session.introspect(token)
-found.active? && found.permits?("uris:catalog:read")
+found.active? && found.permits?("xixo:catalog:read")
 ```
 
 `Introspection` is a `Claims` whose `permit!` also raises when the token is not active.

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

@@ -22,7 +22,7 @@ module Masks
       private
 
         def photo_url
-          held = masks_claims.avatars.photo
+          held = masked.avatars.photo
 
           return nil if held.nil?
           return nil unless held.start_with?("#{masks_config.issuer_for(request)}/")

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

@@ -72,7 +72,7 @@ module Masks
 
         def require_unconfigured_or_manager
           return unless masks_config.configured?(request)
-          return if masks_config.manages?(request, masks_identity)
+          return if masks_config.manages?(request, masked)
 
           @code = "forbidden"
           @description = "only somebody this app lets manage its connection can reconnect or disconnect it"

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

@@ -8,7 +8,7 @@ module Masks
         if masks_configured? && (masks_signed_in? || (masks_tokens && masks_refresh!))
           response.headers["Cache-Control"] = "no-store"
 
-          render json: masks_account
+          render json: masked.to_h
         else
           masks_forget
           masks_refuse_json
@@ -25,6 +25,7 @@ module Masks
         started = masks_session.start(
           state: pending.id,
           resource: masks_config.resource_for(request),
+          scope: masks_config.scope_for(params[:privilege]),
           organization: Masks::Client::Session.organization_key(params[:organization]) ||
             masks_config.organization_for(request)
         )
@@ -88,7 +89,7 @@ module Masks
       private
 
         def renew_session
-          carried = session.to_hash.slice(REQUESTS, HANDSHAKES)
+          carried = session.to_hash.slice(REQUESTS, HANDSHAKES, Masks::Rails::Authentication::STEPPED_UP)
 
           reset_session
           carried.each { |key, value| session[key] = value }

data/lib/masks/rails/authentication.rb

@@ -3,24 +3,18 @@ module Masks
     module Authentication
       extend ActiveSupport::Concern
       include Masks::Rails::Configurable
+      include Masks::Rails::Privileged
 
       included do
         if respond_to?(:helper_method)
-          helper_method :masks_signed_in?, :masks_identity, :masks_tenant, :masks_scopes,
-                        :masks_claims, :masks_organization, :masks_organizations, :masks_role?,
-                        :masks_login_url
-        end
-      end
-
-      class_methods do
-        def masks_members_only!(role: nil, organization: nil, **options)
-          before_action(-> { authorize_masks_member!(*Array(role), organization: organization) },
-                        **options.slice(:only, :except))
+          helper_method :masked, :masks_login_url, :masks_logout_url
         end
       end
 
       REQUESTS = "masks_requests".freeze
       HANDSHAKES = "masks_handshakes".freeze
+      STEPPED_UP = "masks_stepped_up".freeze
+      STEP_UP_WITHIN = 300
 
       def masks_session
         @masks_session ||= masks_config.session_for(request)
@@ -50,8 +44,7 @@ module Masks
 
         session[masks_config.session_key] = held.compact
         @masks_tokens = tokens
-        @masks_identity = held["identity"]
-        @masks_claims = nil
+        @masked = nil
       end
 
       def masks_held
@@ -73,8 +66,19 @@ module Masks
       def masks_forget
         session.delete(masks_config.session_key)
         @masks_tokens = nil
-        @masks_identity = nil
-        @masks_claims = nil
+        @masked = nil
+      end
+
+      def masked
+        @masked ||= if masks_tokens
+          Masked.new(
+            claims: Masks::Client::Claims.new(masks_held["identity"] || {}), scopes: masks_tokens.scopes,
+            config: masks_config, signed_in: masks_signed_in?, access_token: masks_tokens.access_token,
+            expires_at: masks_tokens.expires_at, account_url: masks_account_url
+          )
+        else
+          Masked.nobody(masks_config)
+        end
       end
 
       def masks_signed_in?
@@ -119,46 +123,6 @@ module Masks
         Masks::Rails::Engine.routes.url_helpers.handshake_path
       end
 
-      def masks_identity
-        return @masks_identity if defined?(@masks_identity)
-
-        @masks_identity = masks_held["identity"]
-      end
-
-      def masks_tenant
-        masks_identity&.dig("tenant")
-      end
-
-      def masks_claims
-        @masks_claims ||= Masks::Client::Claims.new(masks_identity || {})
-      end
-
-      def masks_organization
-        held = masks_claims.organization
-
-        held.present? ? held : nil
-      end
-
-      def masks_organizations
-        masks_claims.organizations
-      end
-
-      def masks_role?(*roles)
-        masks_organization&.role?(*roles) || false
-      end
-
-      def masks_scopes
-        masks_tokens&.scopes || []
-      end
-
-      def masks_permits?(scope)
-        masks_scopes.include?(scope.to_s)
-      end
-
-      def masks_access_token
-        masks_tokens&.access_token
-      end
-
       def masks_refresh!
         return false unless masks_configured?
         return false if masks_tokens&.refresh_token.nil?
@@ -203,37 +167,17 @@ module Masks
         "#{request.base_url}#{masks_local_path(masks_config.after_sign_out) || '/'}"
       end
 
-      def masks_login_url(return_to: nil, organization: nil)
+      def masks_login_url(return_to: nil, organization: nil, privilege: nil)
         path = Masks::Rails::Engine.routes.url_helpers.start_path
         query = {
           "return_to" => masks_local_path(return_to),
-          "organization" => Masks::Client::Session.organization_key(organization)
+          "organization" => Masks::Client::Session.organization_key(organization),
+          "privilege" => Array(privilege).join(" ").presence
         }.compact
 
         query.empty? ? path : "#{path}?#{URI.encode_www_form(query)}"
       end
 
-      def masks_account
-        identity = masks_identity || {}
-
-        {
-          "signed_in" => masks_signed_in?,
-          "subject" => identity["sub"],
-          "name" => identity["name"],
-          "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,
-          "organization" => masks_organization&.to_h,
-          "organizations" => masks_organizations.map(&:to_h).presence,
-          "scopes" => masks_scopes,
-          "expires_at" => masks_tokens&.expires_at,
-          "account_url" => masks_account_url
-        }.compact
-      end
-
       def masks_account_url
         "#{masks_config.issuer_for(request).to_s.chomp('/')}/"
       rescue Masks::Rails::Configuration::Unconfigured
@@ -247,17 +191,49 @@ module Masks
         false
       end
 
-      def authorize_masks_member!(*roles, organization: nil)
-        return false unless authenticate_masks!
+      private
 
-        masks_claims.member!(*roles, organization: organization)
-        true
-      rescue Masks::Client::Forbidden => e
-        masks_forbid(e)
-        false
-      end
+        def masks_authorize_session!(wanted)
+          return false unless authenticate_masks!
 
-      private
+          wanted.each { |privilege| masked.member!(privilege) }
+
+          missing = wanted.reject { |privilege| (privilege.scopes - masked.scopes).empty? }.map(&:name)
+          return true if missing.empty?
+
+          if masks_asked_already?(session.delete(STEPPED_UP), missing)
+            raise Masks::Client::Forbidden.new(
+              "insufficient_scope", "this account does not hold the #{missing.join(' and ')} privilege",
+              scope: missing.flat_map { |name| masks_config.privilege(name).scopes }.join(" ")
+            )
+          end
+
+          masks_ask_again(missing)
+          false
+        rescue Masks::Client::Forbidden => e
+          masks_forbid(e)
+          false
+        end
+
+        def masks_asked_already?(asked, missing)
+          asked.is_a?(Hash) && (missing - Array(asked["privileges"])).empty? &&
+            asked["at"].to_i > Time.now.to_i - STEP_UP_WITHIN
+        end
+
+        def masks_ask_again(missing)
+          return_to = request.get? ? request.fullpath : masks_referring_path
+          url = masks_login_url(return_to: return_to, privilege: missing)
+
+          session[STEPPED_UP] = { "privileges" => missing, "at" => Time.now.to_i }
+
+          if masks_wants_json?
+            response.headers["Cache-Control"] = "no-store"
+            render json: { "error" => "privilege_required", "privileges" => missing, "login_url" => url },
+                   status: :forbidden
+          else
+            redirect_to url
+          end
+        end
 
         def masks_forbid(error)
           response.headers["Cache-Control"] = "no-store"

data/lib/masks/rails/configuration.rb

@@ -3,6 +3,10 @@ module Masks
     class Configuration
       class Unconfigured < Masks::Client::Error; end
 
+      Privilege = Struct.new(:name, :scopes, :roles, :organization, keyword_init: true)
+      PRIVILEGE_KEYS = %w[scope role organization].freeze
+
+      attr_reader :privileges
       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, :delegates
@@ -11,6 +15,7 @@ module Masks
 
       def initialize
         @scope = Masks::Client::Session::DEFAULT_SCOPE
+        @privileges = {}
         @resource_scopes = []
         @after_sign_in = "/"
         @after_sign_out = "/"
@@ -89,12 +94,12 @@ module Masks
         true
       end
 
-      def manages?(request, identity = nil)
-        return false unless @manages.respond_to?(:call)
-
-        held = @manages.arity == 1 ? @manages.call(request) : @manages.call(request, identity)
-
-        held ? true : false
+      def manages?(request, masked = nil)
+        case @manages
+        when Symbol, String then masked&.privilege?(@manages) || false
+        when nil then false
+        else (@manages.arity == 1 ? @manages.call(request) : @manages.call(request, masked)) ? true : false
+        end
       end
 
       def can_forget?
@@ -151,12 +156,34 @@ module Masks
         )
       end
 
+      def privileges=(value)
+        @privileges = value.to_h.to_h do |name, spec|
+          held = spec.is_a?(Hash) ? spec.transform_keys(&:to_s) : { "scope" => spec }
+          unknown = held.keys - PRIVILEGE_KEYS
+
+          raise ArgumentError, "the #{name} privilege names #{unknown.join(', ')}, which is not #{PRIVILEGE_KEYS.join(', ')}" if unknown.any?
+
+          [ name.to_s, Privilege.new(name: name.to_s, scopes: Array(held["scope"]).map(&:to_s),
+                                     roles: Array(held["role"]).map(&:to_s), organization: held["organization"]&.to_s) ]
+        end
+      end
+
+      def privilege(name)
+        privileges.fetch(name.to_s) { raise ArgumentError, "Masks::Rails.config.privileges has no #{name}" }
+      end
+
+      def scope_for(requested)
+        wanted = (requested.to_s.split & privileges.keys).flat_map { |name| privileges[name].scopes }
+        wanted.empty? ? nil : (Array(scope) + wanted).uniq
+      end
+
       def approved_scope
         delegated = delegates ? [ Masks::Client::Delegations::SCOPE ] : []
 
-        return Array(scope) + delegated if namespace.blank?
+        asked = (Array(scope) + privileges.values.flat_map(&:scopes)).uniq
+        return asked + delegated if namespace.blank?
 
-        outside = Array(scope).reject { |name| name.to_s.start_with?(namespace) }
+        outside = asked.reject { |name| name.to_s.start_with?(namespace) }
 
         outside + [ namespace ] + delegated
       end

data/lib/masks/rails/masked.rb

@@ -0,0 +1,126 @@
+module Masks
+  module Rails
+    class Masked
+      attr_reader :claims, :scopes, :access_token, :expires_at, :account_url
+
+      def self.nobody(config)
+        new(claims: Masks::Client::Claims.new({}), scopes: [], config: config, signed_in: false)
+      end
+
+      def initialize(claims:, scopes:, config:, signed_in:, access_token: nil, expires_at: nil, account_url: nil)
+        @claims = claims
+        @scopes = Array(scopes).map(&:to_s).freeze
+        @config = config
+        @signed_in = signed_in
+        @access_token = access_token
+        @expires_at = expires_at
+        @account_url = account_url
+      end
+
+      def signed_in?
+        @signed_in
+      end
+
+      def [](claim)
+        claims[claim]
+      end
+
+      def subject
+        claims.subject
+      end
+
+      def name
+        claims["name"]
+      end
+
+      def nickname
+        claims["preferred_username"]
+      end
+
+      def email
+        claims["email"]
+      end
+
+      def email_verified?
+        claims["email_verified"] == true
+      end
+
+      def picture
+        claims.picture
+      end
+
+      def avatars
+        claims.avatars
+      end
+
+      def tenant
+        claims.tenant
+      end
+
+      def organization
+        held = claims.organization
+
+        held.present? ? held : nil
+      end
+
+      def organizations
+        claims.organizations
+      end
+
+      def role?(*roles)
+        organization&.role?(*roles) || false
+      end
+
+      def permits?(scope)
+        scopes.include?(scope.to_s)
+      end
+
+      def privileges
+        return [] unless signed_in?
+
+        @config.privileges.values.select { |privilege| holds?(privilege) }.map(&:name)
+      end
+
+      def privilege?(*names)
+        wanted = names.flatten.map { |name| @config.privilege(name) }
+
+        signed_in? && wanted.all? { |privilege| holds?(privilege) }
+      end
+
+      def holds?(privilege)
+        return false unless (privilege.scopes - scopes).empty?
+
+        member!(privilege)
+        true
+      rescue Masks::Client::Forbidden
+        false
+      end
+
+      def member!(privilege)
+        return if privilege.roles.empty? && privilege.organization.nil?
+
+        claims.member!(*privilege.roles, organization: privilege.organization)
+      end
+
+      def to_h
+        {
+          "signed_in" => signed_in?,
+          "subject" => subject,
+          "name" => name,
+          "nickname" => nickname,
+          "email" => email,
+          "email_verified" => claims["email_verified"],
+          "picture" => picture,
+          "avatars" => avatars.to_h.presence,
+          "tenant" => claims["tenant"],
+          "organization" => organization&.to_h,
+          "organizations" => organizations.map(&:to_h).presence,
+          "scopes" => scopes,
+          "privileges" => privileges,
+          "expires_at" => expires_at,
+          "account_url" => account_url
+        }.compact
+      end
+    end
+  end
+end

data/lib/masks/rails/privileged.rb

@@ -0,0 +1,29 @@
+module Masks
+  module Rails
+    module Privileged
+      extend ActiveSupport::Concern
+      include Masks::Rails::Configurable
+
+      class_methods do
+        def masked!(*privileges, **options)
+          before_action(-> { authorize_masks!(*privileges) }, **options.slice(:only, :except))
+        end
+      end
+
+      def authorize_masks!(*names)
+        privileges = names.flatten.map { |name| masks_config.privilege(name) }
+
+        masks_by_token? ? masks_authorize_token!(privileges) : masks_authorize_session!(privileges)
+      end
+
+      private
+
+        def masks_by_token?
+          return false unless respond_to?(:masks_authorize_token!, true)
+          return true if request.authorization.present? || !respond_to?(:masks_authorize_session!, true)
+
+          masks_tokens.nil?
+        end
+    end
+  end
+end

data/lib/masks/rails/protected_resource.rb

@@ -3,27 +3,19 @@ module Masks
     module ProtectedResource
       extend ActiveSupport::Concern
       include Masks::Rails::Configurable
-
-      class_methods do
-        def masks_protect!(**options)
-          before_action(-> { masks_authenticate!(**options) }, **options.slice(:only, :except))
-        end
-      end
+      include Masks::Rails::Privileged
 
       def masks_resource
         @masks_resource ||= masks_config.resource_server_for(request)
       end
 
-      def masks_claims
-        @masks_claims if defined?(@masks_claims)
-      end
+      def masked
+        return (defined?(super) ? super : Masked.nobody(masks_config)) unless defined?(@masks_token_claims)
 
-      def masks_authenticate!(scope: nil, role: nil, organization: nil, **)
-        @masks_claims = masks_resource.authenticate(request.authorization, scope: scope, role: role,
-                                                                           organization: organization, **masks_proof)
-      rescue Masks::Client::Challenge => e
-        masks_challenge(e)
-        false
+        @masked_by_token ||= Masked.new(
+          claims: @masks_token_claims, scopes: @masks_token_claims.scopes, config: masks_config, signed_in: true,
+          access_token: masks_resource.token(request.authorization), expires_at: @masks_token_claims.expires_at
+        )
       end
 
       def masks_authenticate(scope: nil, role: nil, organization: nil)
@@ -52,6 +44,25 @@ module Masks
       def masks_resource_metadata
         masks_resource.metadata
       end
+
+      private
+
+        def masks_authorize_token!(privileges)
+          claims = masks_resource.authenticate(request.authorization, scope: privileges.flat_map(&:scopes).uniq,
+                                                                      **masks_proof)
+
+          privileges.each do |privilege|
+            next if privilege.roles.empty? && privilege.organization.nil?
+
+            claims.member!(*privilege.roles, organization: privilege.organization)
+          end
+
+          @masks_token_claims = claims
+          true
+        rescue Masks::Client::Challenge => e
+          masks_challenge(e)
+          false
+        end
     end
   end
 end

data/lib/masks/rails.rb

@@ -31,6 +31,8 @@ require_relative "client"
 require_relative "rails/credentials"
 require_relative "rails/configuration"
 require_relative "rails/configurable"
+require_relative "rails/masked"
+require_relative "rails/privileged"
 require_relative "rails/authentication"
 require_relative "rails/protected_resource"
 require_relative "rails/engine"

data/lib/masks/version.rb

@@ -1,3 +1,3 @@
 module Masks
-  VERSION = "0.9.1".freeze
+  VERSION = "0.10.0".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: masks
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 0.10.0
 platform: ruby
 authors:
 - the masks authors
@@ -73,6 +73,8 @@ files:
 - lib/masks/rails/configuration.rb
 - lib/masks/rails/credentials.rb
 - lib/masks/rails/engine.rb
+- lib/masks/rails/masked.rb
+- lib/masks/rails/privileged.rb
 - lib/masks/rails/protected_resource.rb
 - lib/masks/version.rb
 homepage: https://github.com/masksrb/masks