masks 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4455d2e731a770253802292bce1dd21a9b97c05489e65ba4a1f310c24873b79
-  data.tar.gz: df05e39f40a1f08fbb77897549c584653bf17676c3e6b13b64220e1751360e64
+  metadata.gz: 5da19b0cb3099ebe46f2b4509615a75422fa0b2820abb799e8f182ce11f456ad
+  data.tar.gz: 4d5d6b573cccbca63439587cd3363d22be28dd0d8ff95051f32dcc8252494185
 SHA512:
-  metadata.gz: 39e55aecad7e80a3cef669b9bcbe16f6f942c326bf98a9f9da954663365740d9e31a814a3da644ef68bd0090f040f853ff4b3bdda34f2f8fe6dd4b749190d138
-  data.tar.gz: 4cca8c0d431151c0a0865969dcc38767388ec4f93c1ab5e2b824e7dd875f8a38135969d7b8ed5a1966eb9b0f51b3fb60e8cff887c67d180561b3474e47653d84
+  metadata.gz: 130ccd4e8a1ca7ddfe996f7439af4dc800501ea0a81ec0a18561475447931af40affb0cd0e2a66aa191d28d93f677046f49b7d5db6a913426fa21114d1bcbb68
+  data.tar.gz: bd818590edc19a344daf59e755d8657da71e10f2017fc3b8ffe95ed6f8452f804a6ccdc7da621425b288c5934b25b5c39bd41923d13983e16fab9ab144bdfd78

data/CHANGELOG.md

@@ -1,5 +1,44 @@
 # 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)
 
 

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,10 +97,13 @@ 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.
@@ -155,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"
 )
@@ -169,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`.
 
@@ -181,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/"
 )
@@ -202,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
 ```
@@ -221,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/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,10 +27,6 @@ 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?
@@ -51,6 +43,15 @@ module Masks
 
       private
 
+        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

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/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

@@ -4,6 +4,7 @@ Masks::Rails::Engine.routes.draw do
   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/delegations/fake.rb

@@ -0,0 +1,91 @@
+require "masks/client"
+
+module Masks
+  module Client
+    class Delegations
+      class Fake
+        Connected = Struct.new(:connection, :provider, :subject, :secret, :refused, :unavailable, keyword_init: true)
+
+        attr_reader :releases, :redirect_uri
+
+        def initialize(redirect_uri: "https://app.test/connect/callback", lifetime: 3600)
+          @redirect_uri = redirect_uri
+          @lifetime = lifetime
+          @codes = {}
+          @connections = {}
+          @releases = 0
+          @lock = Mutex.new
+        end
+
+        def start(provider:, prompt: nil, max_age: nil, state: SecureRandom.urlsafe_base64(24))
+          query = URI.encode_www_form({ "provider" => provider, "state" => state, "prompt" => prompt, "max_age" => max_age }.compact)
+
+          { "url" => "https://masks.fake/authorize?#{query}", "state" => state, "verifier" => SecureRandom.hex(16), "provider" => provider.to_s }
+        end
+
+        def approve(started, subject: "fake-subject", connection: SecureRandom.uuid)
+          code = SecureRandom.hex(12)
+
+          @lock.synchronize do
+            @codes[code] = { "provider" => started["provider"], "subject" => subject, "connection" => connection }
+          end
+
+          { "code" => code, "state" => started["state"] }
+        end
+
+        def deny(started, error: "access_denied", description: "the person declined")
+          { "error" => error, "error_description" => description, "state" => started["state"] }
+        end
+
+        def finish(params:, started:)
+          params = params.to_h.transform_keys(&:to_s)
+
+          raise Refused.new(params["error"], params["error_description"]) if params["error"].to_s != ""
+          raise Refused.new("invalid_state", "the state did not match the one this connection started with") unless params["state"] == started["state"]
+
+          granted = @lock.synchronize { @codes.delete(params["code"]) }
+
+          raise Refused.new("invalid_grant", "that code is not valid") if granted.nil?
+
+          secret = SecureRandom.hex(16)
+
+          @lock.synchronize do
+            @connections[granted["connection"]] = Connected.new(
+              connection: granted["connection"], provider: granted["provider"], subject: granted["subject"], secret: secret
+            )
+          end
+
+          Held.new(connection: granted["connection"], provider: granted["provider"], provider_name: granted["provider"].to_s.capitalize,
+                   label: nil, subject: granted["subject"], secret: secret)
+        end
+
+        def token(secret, connection:)
+          held = @lock.synchronize { @connections[connection.to_s] }
+
+          raise Refused.new("invalid_grant", "that connection is unknown") if held.nil?
+          raise Unavailable.new("masks is not answering", secret: secret) if held.unavailable
+          raise Refused.new("invalid_grant", held.refused, secret: secret) if held.refused
+          raise Refused.new("invalid_grant", "that refresh token is not valid or has expired") unless held.secret == secret.to_s
+
+          rotated = SecureRandom.hex(16)
+
+          @lock.synchronize do
+            held.secret = rotated
+            @releases += 1
+          end
+
+          Upstream.new(access_token: "#{held.provider}-access-#{@releases}", expires_at: Time.now.to_i + @lifetime,
+                       scope: "", secret: rotated)
+        end
+
+        def revoke(connection, reason: "the person stopped this application using that account")
+          @lock.synchronize { @connections.fetch(connection.to_s).refused = reason }
+        end
+
+        def unavailable(connection, now: true)
+          @lock.synchronize { @connections.fetch(connection.to_s).unavailable = now }
+        end
+      end
+    end
+  end
+end

data/lib/masks/client/delegations.rb

@@ -0,0 +1,117 @@
+module Masks
+  module Client
+    class Delegations
+      SCOPE = "masks:delegate:".freeze
+      UPSTREAM_ACCESS_TOKEN = "urn:masks:params:oauth:token-type:upstream_access_token".freeze
+      REFUSALS = %w[invalid_grant insufficient_scope invalid_target unauthorized_client access_denied
+                    login_required interaction_required consent_required invalid_scope].freeze
+
+      class Refused < Error
+        attr_reader :code, :description, :secret
+
+        def initialize(code, description, secret: nil)
+          super([ code, description ].compact.join(": "))
+
+          @code = code
+          @description = description
+          @secret = secret
+        end
+
+        def signed_in_again?
+          %w[login_required interaction_required].include?(code)
+        end
+      end
+
+      class Unavailable < Error
+        attr_reader :secret
+
+        def initialize(message, secret: nil)
+          super(message)
+
+          @secret = secret
+        end
+      end
+
+      Held = Struct.new(:connection, :provider, :provider_name, :label, :subject, :secret, keyword_init: true)
+
+      Upstream = Struct.new(:access_token, :expires_at, :scope, :secret, keyword_init: true) do
+        def expired?(leeway: 60)
+          Time.now.to_i + leeway >= expires_at.to_i
+        end
+      end
+
+      attr_reader :issuer, :client_id, :client_secret, :redirect_uri
+
+      def initialize(issuer:, client_id:, client_secret:, redirect_uri:)
+        @issuer = Issuer.resolve(issuer)
+        @client_id = client_id
+        @client_secret = client_secret
+        @redirect_uri = redirect_uri
+      end
+
+      def start(provider:, prompt: nil, max_age: nil, state: SecureRandom.urlsafe_base64(24))
+        started = session.start(scope: [ "openid", "offline_access", "#{SCOPE}#{provider}" ], prompt: prompt,
+                                max_age: max_age, state: state)
+
+        { "url" => started[:url], "state" => started[:state], "verifier" => started[:verifier], "provider" => provider.to_s }
+      end
+
+      def finish(params:, started:)
+        params = params.to_h.transform_keys(&:to_s)
+        started = started.to_h.transform_keys(&:to_s)
+
+        raise Refused.new(params["error"], params["error_description"]) if params["error"].to_s != ""
+
+        unless params["state"].to_s != "" && OpenSSL.secure_compare(params["state"].to_s, started["state"].to_s)
+          raise Refused.new("invalid_state", "the state did not match the one this connection started with")
+        end
+
+        tokens = answered { session.complete(code: params["code"].to_s, verifier: started["verifier"].to_s) }
+        held = tokens.delegations.find { |one| one["provider"] == started["provider"] }
+
+        raise Refused.new("access_denied", "masks connected nothing for #{started['provider']}") if held.nil?
+        raise Refused.new("invalid_grant", "masks issued no refresh token to keep the connection with") if tokens.refresh_token.to_s == ""
+
+        Held.new(
+          connection: held["connection"], provider: held["provider"], provider_name: held["provider_name"],
+          label: held["label"], subject: held["subject"], secret: tokens.refresh_token
+        )
+      end
+
+      def token(secret, connection:)
+        refreshed = answered { session.refresh(secret.to_s) }
+        rotated = refreshed.refresh_token.to_s == "" ? secret : refreshed.refresh_token
+
+        released = answered(secret: rotated) do
+          session.exchange(refreshed.access_token, requested_token_type: UPSTREAM_ACCESS_TOKEN, audience: connection.to_s)
+        end
+
+        Upstream.new(access_token: released.access_token, expires_at: released.expires_at, scope: released.scope, secret: rotated)
+      end
+
+      private
+
+        def session
+          @session ||= Session.new(issuer: issuer, client_id: client_id, client_secret: client_secret, redirect_uri: redirect_uri)
+        end
+
+        def answered(secret: nil)
+          yield
+        rescue Unregistered
+          raise
+        rescue Rejected => e
+          raise Unavailable.new("masks answered #{e.status}: #{e.message}", secret: secret) if unavailable?(e)
+
+          raise Refused.new(e.code, e.description, secret: secret)
+        rescue Unreachable => e
+          raise Unavailable.new(e.message, secret: secret)
+        end
+
+        def unavailable?(rejection)
+          return false if REFUSALS.include?(rejection.code)
+
+          rejection.code == "temporarily_unavailable" || rejection.status.to_i >= 500 || rejection.status.to_i == 429
+        end
+    end
+  end
+end

data/lib/masks/client/handshake.rb

@@ -5,16 +5,18 @@ module Masks
       GRANT_TYPES = %w[authorization_code refresh_token].freeze
       AUTH_METHOD = "client_secret_basic".freeze
 
-      attr_reader :issuer, :name, :resource, :redirect_uris, :scope, :return_to
+      attr_reader :issuer, :name, :resource, :redirect_uris, :scope, :return_to,
+                  :backchannel_logout_uri
 
       def initialize(issuer, name:, resource:, redirect_uris:, return_to:,
-                     scope: Session::DEFAULT_SCOPE)
+                     scope: Session::DEFAULT_SCOPE, backchannel_logout_uri: nil)
         @issuer = Issuer.resolve(issuer)
         @name = name.to_s
         @resource = resource.to_s
         @redirect_uris = Array(redirect_uris).map(&:to_s)
         @scope = Array(scope).flat_map { |value| value.to_s.split(/\s+/) }.reject(&:empty?)
         @return_to = return_to.to_s
+        @backchannel_logout_uri = backchannel_logout_uri&.to_s
       end
 
       def endpoint
@@ -34,6 +36,7 @@ module Masks
           [ "state", state ]
         ]
 
+        query << [ "backchannel_logout_uri", backchannel_logout_uri ] if backchannel_logout_uri
         redirect_uris.each { |uri| query << [ "redirect_uris", uri ] }
 
         "#{endpoint}?#{URI.encode_www_form(query)}"
@@ -61,7 +64,8 @@ module Masks
           redirect_uris: redirect_uris,
           grant_types: GRANT_TYPES,
           scope: scope,
-          token_endpoint_auth_method: AUTH_METHOD
+          token_endpoint_auth_method: AUTH_METHOD,
+          backchannel_logout_uri: backchannel_logout_uri
         )
       end
 

data/lib/masks/client/introspection.rb

@@ -5,7 +5,7 @@ module Masks
         to_h["active"] == true
       end
 
-      def username
+      def nickname
         self["username"]
       end
 

data/lib/masks/client/issuer.rb

@@ -51,6 +51,10 @@ module Masks
         discovery.fetch(name) { raise Rejected.new("invalid_issuer", "#{url} publishes no #{name}") }
       end
 
+      def backchannel_logout?
+        discovery["backchannel_logout_supported"] == true
+      end
+
       def avatar_styles
         discovery["avatar_styles_supported"] || Claims::Avatars::STYLES
       end

data/lib/masks/client/logout.rb

@@ -0,0 +1,60 @@
+module Masks
+  module Client
+    class Logout
+      EVENT = "http://schemas.openid.net/event/backchannel-logout".freeze
+      ALGORITHMS = Verifier::ALGORITHMS
+      LEEWAY = 60
+
+      class << self
+        def verify(token, issuer:, audience:, algorithms: ALGORITHMS)
+          held = Verifier
+            .new(issuer, audience: audience, algorithms: algorithms)
+            .verify(token, required: %w[iss aud iat jti events])
+
+          new(held).validate!
+        end
+      end
+
+      attr_reader :claims
+
+      def initialize(claims)
+        @claims = claims
+      end
+
+      def subject
+        claims["sub"]
+      end
+
+      def sid
+        claims["sid"]
+      end
+
+      def jti
+        claims["jti"]
+      end
+
+      def issued_at
+        Time.at(claims["iat"].to_i).utc
+      end
+
+      def validate!
+        refuse!("logout token carries a nonce, so it is an id token") if claims.key?("nonce")
+        refuse!("logout token names neither a subject nor a session") if subject.nil? && sid.nil?
+        refuse!("logout token was issued in the future") if issued_at > Time.now.utc + LEEWAY
+
+        held = claims["events"]
+
+        refuse!("logout token has no events claim") unless held.is_a?(Hash)
+        refuse!("logout token is not about a logout") unless held[EVENT].is_a?(Hash)
+
+        self
+      end
+
+      private
+
+        def refuse!(said)
+          raise InvalidToken, said
+        end
+    end
+  end
+end

data/lib/masks/client/registration.rb

@@ -23,7 +23,8 @@ module Masks
           "token_endpoint_auth_method" => attributes[:token_endpoint_auth_method],
           "application_type" => attributes[:application_type],
           "client_uri" => attributes[:client_uri],
-          "logo_uri" => attributes[:logo_uri]
+          "logo_uri" => attributes[:logo_uri],
+          "backchannel_logout_uri" => attributes[:backchannel_logout_uri]
         }.reject { |_, value| value.nil? || (value.respond_to?(:empty?) && value.empty?) }
       end
 
@@ -32,8 +33,6 @@ module Masks
         list.empty? ? default : list
       end
 
-      # Rebuild a registration from what a consumer stored, so RFC 7592's read,
-      # update and delete are reachable without having just created it.
       def self.held(issuer, credentials)
         held = credentials.to_h.transform_keys(&:to_s)
         return nil if held["registration_client_uri"].blank? || held["registration_access_token"].blank?

data/lib/masks/client/session.rb

@@ -14,7 +14,7 @@ module Masks
       end
 
       def start(resource: nil, prompt: nil, scope: nil, state: SecureRandom.urlsafe_base64(24),
-                nonce: SecureRandom.urlsafe_base64(24))
+                nonce: SecureRandom.urlsafe_base64(24), max_age: nil)
         pkce = Pkce.generate
         scopes = Array(scope || self.scope)
         nonce = nil unless scopes.include?("openid")
@@ -33,6 +33,7 @@ module Masks
 
         Array(resource).each { |value| pairs << [ "resource", value ] }
         pairs << [ "prompt", prompt ] if prompt
+        pairs << [ "max_age", max_age.to_i ] if max_age
 
         {
           url: "#{issuer.endpoint('authorization_endpoint')}?#{URI.encode_www_form(pairs)}",
@@ -69,7 +70,7 @@ module Masks
         Tokens.granted(HTTP.post_form(issuer.endpoint("token_endpoint"), form, authorization))
       end
 
-      def exchange(subject_token, scope: nil, resource: nil, lifetime: nil)
+      def exchange(subject_token, scope: nil, resource: nil, lifetime: nil, requested_token_type: nil, audience: nil)
         form = [
           [ "grant_type", Tokens::EXCHANGE ],
           [ "client_id", client_id ],
@@ -77,6 +78,9 @@ module Masks
           [ "subject_token_type", Tokens::ACCESS_TOKEN ]
         ]
 
+        form << [ "requested_token_type", requested_token_type ] if requested_token_type
+        Array(audience).each { |value| form << [ "audience", value ] }
+
         form << [ "scope", Array(scope).join(" ") ] if scope
         form << [ "requested_lifetime", lifetime.to_i ] if lifetime
         Array(resource).each { |value| form << [ "resource", value ] }
@@ -92,6 +96,10 @@ module Masks
         true
       end
 
+      def logout_token(token)
+        Logout.verify(token, issuer: issuer, audience: client_id)
+      end
+
       def end_session_url(post_logout_redirect_uri: nil, state: nil, id_token_hint: nil)
         pairs = [ [ "client_id", client_id ] ]
         pairs << [ "id_token_hint", id_token_hint ] if id_token_hint

data/lib/masks/client/tokens.rb

@@ -4,7 +4,8 @@ module Masks
       EXCHANGE = "urn:ietf:params:oauth:grant-type:token-exchange".freeze
       ACCESS_TOKEN = "urn:ietf:params:oauth:token-type:access_token".freeze
 
-      attr_reader :access_token, :id_token, :refresh_token, :token_type, :scope, :expires_in, :obtained_at
+      attr_reader :access_token, :id_token, :refresh_token, :token_type, :scope, :expires_in, :obtained_at,
+                  :delegations
 
       def self.granted(body)
         token = new(body)
@@ -26,6 +27,7 @@ module Masks
         @token_type = body["token_type"] || "Bearer"
         @scope = body["scope"].to_s
         @expires_in = body["expires_in"].to_i
+        @delegations = Array(body["delegations"])
         @obtained_at = Time.now.to_i
       end
 

data/lib/masks/client.rb

@@ -19,33 +19,79 @@ require_relative "client/claims"
 require_relative "client/introspection"
 require_relative "client/session"
 require_relative "client/verifier"
+require_relative "client/logout"
 require_relative "client/resource"
 require_relative "client/rack"
 require_relative "client/registration"
 require_relative "client/handshake"
+require_relative "client/delegations"
 
 module Masks
+  # = Masks::Client
+  #
+  # The protocol half of the gem: plain Ruby, no \Rails, no database. Every
+  # entry point here is a class method that builds one of the objects below.
+  #
+  # Which one you want depends on what the application is doing:
+  #
+  # [issuer]    an app signing people in — discovery, PKCE, the code exchange
+  # [verifier]  an API checking a bearer it was handed
+  # [resource]  an API publishing what it is and which scopes it takes
+  # [handshake] an app registering itself, once, without a copied secret
+  #
+  # Everything reachable from here talks HTTP to a masks issuer and holds no
+  # state of its own beyond the discovery cache in ::registry.
   module Client
     class << self
+      # The process-wide cache of resolved issuers, so discovery is fetched
+      # once rather than per request.
+      #
+      # @return [Masks::Client::Registry]
       def registry
         @registry ||= Registry.new
       end
 
+      # Resolves +url+ through its discovery document and returns the issuer
+      # it describes. Cached in ::registry, so calling this per request is
+      # cheap after the first.
+      #
+      #   issuer = Masks::Client.issuer("https://auth.example")
+      #   issuer.authorization_url(client_id: id, redirect_uri: uri)
+      #
+      # @return [Masks::Client::Issuer]
       def issuer(url, **options)
         Issuer.resolve(url, **options)
       end
 
+      # Checks tokens minted by the issuer at +url+ against +audience+ — the
+      # API's own URL, which the token names in +aud+. A token issued for
+      # anything else is refused rather than merely noted.
+      #
+      # @return [Masks::Client::Verifier]
       def verifier(url, audience:, **options)
         Verifier.new(issuer(url), audience: audience, **options)
       end
 
+      # Describes this API to callers: the scopes it accepts and the issuer
+      # that may mint tokens for it, served as RFC 9728 metadata.
+      #
+      # @return [Masks::Client::Resource]
       def resource(url, issuer:, **options)
         Resource.new(issuer: issuer, url: url, **options)
       end
 
+      # Registers this application against a masks issuer. A person approves
+      # it in their browser and the credentials come back server to server, so
+      # no secret is pasted between the two.
+      #
+      # @return [Masks::Client::Handshake]
       def handshake(url, **options)
         Handshake.new(url, **options)
       end
+
+      def delegations(issuer, **options)
+        Delegations.new(issuer: issuer, **options)
+      end
     end
   end
 end

data/lib/masks/rails/configuration.rb

@@ -5,8 +5,9 @@ module Masks
 
       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
+                    :credentials_path, :authenticate_everything, :delegates
+      attr_writer :issuer, :redirect_uri, :name, :credentials, :store, :forget, :logged_out,
+                  :delegation_redirect_uri
 
       def initialize
         @scope = Masks::Client::Session::DEFAULT_SCOPE
@@ -17,12 +18,9 @@ module Masks
         @sign_out_of_issuer = false
         @parent_controller = "ActionController::Base"
         @authenticate_everything = false
+        @delegates = false
       end
 
-      # An app that has not said where to keep its credentials gets one file
-      # under the Rails root, so the handshake works before anybody writes a
-      # `store` lambda. `things` overrides both because it is multi-tenant,
-      # which is the interesting case rather than the common one.
       def default_credentials
         @default_credentials ||= Credentials.new(
           credentials_path || ::Rails.root.join("config", "masks.json")
@@ -43,6 +41,12 @@ module Masks
           "#{request.base_url}#{routes.callback_path}"
       end
 
+      def delegation_redirect_uri_for(request)
+        return nil unless delegates
+
+        resolve(@delegation_redirect_uri, request)
+      end
+
       def resource_for(request)
         resolve(@resource, request)
       end
@@ -66,8 +70,21 @@ module Masks
         client_id_for(request).present?
       end
 
-      # An app that keeps its own credentials has to say how to drop them, and
-      # until it does the engine does not offer a button it cannot honour.
+      def backchannel_logout_uri_for(request)
+        return nil unless @logged_out.respond_to?(:call)
+        return nil unless Masks::Client::Issuer.resolve(issuer_for(request)).backchannel_logout?
+
+        "#{request.base_url}#{routes.backchannel_logout_path}"
+      end
+
+      def logged_out!(request, logout)
+        return false unless @logged_out.respond_to?(:call)
+
+        @logged_out.arity == 1 ? @logged_out.call(logout) : @logged_out.call(request, logout)
+
+        true
+      end
+
       def can_forget?
         @forget.respond_to?(:call) || !@store.respond_to?(:call)
       end
@@ -85,10 +102,6 @@ module Masks
         @store.call(request, registration)
       end
 
-      # The engine depends on `handshake_endpoint` being in the discovery
-      # document, and on the approval flow behind it. An issuer that predates
-      # both should say so here rather than at the one screen that exists to
-      # be the first thing anybody touches.
       MINIMUM_ISSUER = 1
 
       def issuer_speaks!(request)
@@ -132,22 +145,21 @@ module Masks
           name: name_for(request),
           resource: Array(resource_for(request)).first ||
             raise(Unconfigured, "Masks::Rails.config.resource is not set"),
-          redirect_uris: [ redirect_uri_for(request) ],
+          redirect_uris: [ redirect_uri_for(request), delegation_redirect_uri_for(request) ].compact.uniq,
           return_to: return_to_for(request),
-          scope: approved_scope
+          scope: approved_scope,
+          backchannel_logout_uri: backchannel_logout_uri_for(request)
         )
       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?
+        delegated = delegates ? [ Masks::Client::Delegations::SCOPE ] : []
+
+        return Array(scope) + delegated if namespace.blank?
 
         outside = Array(scope).reject { |name| name.to_s.start_with?(namespace) }
 
-        outside + [ namespace ]
+        outside + [ namespace ] + delegated
       end
 
       def return_to_for(request)

data/lib/masks/rails/credentials.rb

@@ -1,9 +1,5 @@
 module Masks
   module Rails
-    # The default place a single-tenant app keeps what the handshake gives it,
-    # so `config.store` has something to be before a consumer writes one. An
-    # app with more than one issuer wants its own — `things` keeps these on
-    # `tenants`, because a handshake is per tenant there.
     class Credentials
       KEYS = %w[client_id client_secret registration_access_token registration_client_uri].freeze
 

data/lib/masks/rails/engine.rb

@@ -5,11 +5,6 @@ module Masks
 
       config.masks = Masks::Rails.config
 
-      # Opt-in, not blanket. This used to `include Masks::Rails::Authentication`
-      # into every controller in the host app, which lands twenty-five `masks_*`
-      # methods and four helper_methods on code the consumer owns, with no way
-      # to say no — and a name collision found that way is the kind of thing
-      # `grants:` versus `scope:` already cost this project once.
       initializer "masks.authentication" do
         ActiveSupport.on_load(:action_controller) do
           include Masks::Rails::Authentication if Masks::Rails.config.authenticate_everything

data/lib/masks/rails.rb

@@ -1,5 +1,31 @@
 require "rails"
 
+module Masks
+  # = Masks::Rails
+  #
+  # The consumer half: a \Rails engine that mounts the code flow into an
+  # application, so signing in against a masks issuer is configuration rather
+  # than a controller you write.
+  #
+  # It loads only when +Rails::Engine+ is already defined. Requiring the gem
+  # from a plain Ruby process gets Masks::Client and nothing else.
+  #
+  # Three pieces do the work:
+  #
+  # [Configuration]    the issuer, credentials and routes, set once in an
+  #                    initializer and validated on boot rather than on the
+  #                    first request that needs them
+  # [Authentication]   +masks_login_url+, the callback, and the session the
+  #                    app reads +current_actor+ from
+  # [ProtectedResource] the other direction — checking a bearer this app was
+  #                    handed, for an API rather than a browser
+  #
+  # This engine is the client. It never runs in the same process as the
+  # provider, which is a standalone deployable holding its own database.
+  module Rails
+  end
+end
+
 require_relative "version"
 require_relative "client"
 require_relative "rails/credentials"

data/lib/masks/version.rb

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

data/lib/masks.rb

@@ -1,3 +1,20 @@
+# = \Masks
+#
+# Signs an application in against a masks issuer.
+#
+# The gem is two halves. Masks::Client is plain Ruby and speaks the protocol —
+# discovery, PKCE, the code exchange, token verification. Masks::Rails mounts
+# that flow into a \Rails app, and loads only when +Rails::Engine+ is already
+# defined, so requiring this gem outside \Rails costs nothing.
+#
+#   issuer = Masks::Client.issuer("https://auth.example")
+#   issuer.authorization_url(client_id: id, redirect_uri: uri)
+#
+# The provider itself is not in here. It is a deployable that holds a database
+# and the per-tenant signing keys, and it stays standalone.
+module Masks
+end
+
 require_relative "masks/version"
 require_relative "masks/client"
 

metadata

@@ -1,10 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: masks
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
-- geiger
+- the masks authors
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
@@ -36,6 +36,7 @@ files:
 - 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/logouts_controller.rb
 - app/controllers/masks/rails/sessions_controller.rb
 - app/views/layouts/masks/rails/plain.html.erb
 - app/views/masks/rails/handshakes/refused.html.erb
@@ -46,11 +47,14 @@ files:
 - lib/masks.rb
 - lib/masks/client.rb
 - lib/masks/client/claims.rb
+- lib/masks/client/delegations.rb
+- lib/masks/client/delegations/fake.rb
 - lib/masks/client/errors.rb
 - lib/masks/client/handshake.rb
 - lib/masks/client/http.rb
 - lib/masks/client/introspection.rb
 - lib/masks/client/issuer.rb
+- lib/masks/client/logout.rb
 - lib/masks/client/pkce.rb
 - lib/masks/client/rack.rb
 - lib/masks/client/registration.rb