masks 0.8.0 → 0.9.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ec26aa454cf249dd26ce7e15444b43890e4e75954968c76cba3297b63f9819e
-  data.tar.gz: 19609ef3a180ab7d6c675cac13cef843adb3ffc742d83b7fd64d7120bbcc93b5
+  metadata.gz: a915522b23f370321d7eca71a6d4965804d6988e441f6f019b1b1817bab7f0c3
+  data.tar.gz: 05f68f68ed521f6d378393cadda81bec7b984802f10ab651a5eaa8c9b31d4a7c
 SHA512:
-  metadata.gz: 4a02a532dc018b73c27b350da38335b5ec27c5665d8b498564fd11b220e386919df8ecc9a24b80fb62f21d193c7a66166e99d2dc41c86fef3cb515f5aacc2b0d
-  data.tar.gz: fbbb524a91dda55fc6ccf631d1ef8b270b9ff9835b894855dcd0dd07a054fcfb380c6fdea75930b93950909ba1e3618940215418c9fca7f0a5f32e30b33c96b4
+  metadata.gz: 13467dcc61e51edbb9a7493feb38ccb2cf0f1f42db9a127cb37ccb89c0bf3187de211f928bce1dd854d711f3418a0b504bb3a2b0e645ee8ac7d864b47fd8d4c5
+  data.tar.gz: 4b0b6abea05f55b54b9280de48c8096a8406fdd82e7dcb575584b56679ccb91fc3af11c2766cda26cee44ae8ace19f384a5714a0e3a81b029bcead957d8ba008

data/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## [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)
+
+
+### Fixes
+
+* **client:** an error the issuer sends back is shown rather than retried, and the engine tests hold the new callback behaviour ([36adb9b](https://github.com/masksrb/masks/commit/36adb9b57a2379b8d7ce1d16f2e04e8c244baa7d))
+
+## [0.9.0](https://github.com/masksrb/masks/compare/gem/v0.8.0...gem/v0.9.0) (2026-10-04)
+
+
+### ⚠ BREAKING CHANGES
+
+* **client:** a connected app refuses reconnecting and disconnecting until config.manages is set, for example config.manages = ->(request, identity) { identity["sub"] == ENV["OWNER_SUB"] }.
+
+### Fixes
+
+* **client:** a resource server refuses a DPoP-bound token presented as Bearer, and checks the proof one presented as DPoP ([9a3fe8a](https://github.com/masksrb/masks/commit/9a3fe8adac09fd70a7059674d8c34333c8f3ff92))
+* **client:** a return_to a browser would read as another host is refused, and signing out revokes the refresh token ([de27168](https://github.com/masksrb/masks/commit/de2716872955ba124a8a3ec1dbe07cb043fd0260))
+* **client:** a sign-in callback this browser no longer holds goes on to the app or starts sign-in again, instead of ending on an error ([a1ba84c](https://github.com/masksrb/masks/commit/a1ba84c4a974897bdb80b1f32da5c0b72f83ca79))
+* **client:** every resource in a process shares one store of seen DPoP proofs, and a refused proof is challenged with the DPoP scheme ([f8d1fe2](https://github.com/masksrb/masks/commit/f8d1fe2487e0705c914ea3d3ae7f686152cad6b3))
+* **client:** only somebody config.manages approves can reconnect or disconnect a connected app ([5665129](https://github.com/masksrb/masks/commit/566512979dc00a36148de57b4ea9954fc68db10b))
+
+
+### Documentation
+
+* every guide, the reference prose, and the READMEs are checked against the code, shortened, and corrected ([94782d1](https://github.com/masksrb/masks/commit/94782d1fbfe363e90c40f0c728a241de9738e138))
+* the plan holds only what is left, and the READMEs match the engine layout and the code ([1615722](https://github.com/masksrb/masks/commit/1615722f88ae5f7d19955ff686dcef9f64a6326f))
+
+
+### Refactoring
+
+* **client:** the issuer version check nothing called, Registry#urls and Verifier#tenant go ([6b8cf05](https://github.com/masksrb/masks/commit/6b8cf0550b96f6b1b3b415ff27f655f90614bdfe))
+* **engine:** deleting and downloading an account share one check for a fresh sign-in, and PKCE uses the client's one base64url digest ([6c08fcf](https://github.com/masksrb/masks/commit/6c08fcf709a08dbafd0a551801eaf43a4c325b75))
+* **engine:** one partial carries a tenant's email wording, one query loads it, and authorization_details narrow in one place ([1b2df29](https://github.com/masksrb/masks/commit/1b2df29380b2c2c8dc6b87d45d60b4ef23255b26))
+
 ## [0.8.0](https://github.com/masksrb/masks/compare/gem/v0.7.0...gem/v0.8.0) (2026-09-28)
 
 

data/README.md

@@ -8,53 +8,50 @@ Sign a Ruby or Rails app in against a [masks](https://github.com/masksrb/masks)
 gem "masks"
 ```
 
-Three parts, in one gem. **Consumers spend tokens. Resource servers accept them.** Most
-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.
+The gem signs people in to an app, and accepts the tokens masks issues when the app is also a
+resource server. Its Rails engine loads only when Rails does, so a Sinatra, Hanami, or plain Rack
+app pulls in `jwt` and nothing else. See
+[Connecting via SDK](https://masks.pages.dev/guides/connecting-via-sdk/) for what it covers beside
+the browser package.
 
 ## Rails
 
-One command to install, and the app is connected by somebody approving it — no client
-id to copy, no secret to paste anywhere.
-
-```
-bin/rails generate masks:install
+```sh
+bin/rails generate masks:install --resource https://app.example.com
 ```
 
 That mounts the engine at `/auth`, writes `config/initializers/masks.rb`, and gitignores
 the file credentials land in. Set `MASKS_ISSUER`, start the app, and open
-`/auth/handshake`.
+`/auth/handshake`. [Rails apps](https://masks.pages.dev/guides/rails/) walks through the rest.
 
 ### The handshake
 
-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.**
+An app connects to its issuer by somebody approving it. An unconnected app sends the browser to
+the issuer's approval screen, and the server redeems the one-time token that comes back, so the
+client secret never passes through the browser. The handshake registers the app for
+`config.resource`, an absolute URL on the app's own origin, and refuses without one. A connected app
+asks before it rotates, because reconnecting takes it offline for a moment.
 
-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.
+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:
 
-The engine writes what comes back to `config/masks.json`, mode 600. An app that wants
-somewhere else says so:
+```ruby
+config.manages = ->(request, identity) { identity["sub"] == ENV["OWNER_SUB"] }
+```
+
+The engine writes what comes back to `config/masks.json`, mode 600. A multi-tenant app keeps it
+somewhere else with two callables:
 
 ```ruby
 config.credentials = ->(request) { Tenant.for(request).masks_credentials }
 config.store = ->(request, registration) { Tenant.for(request).connect!(registration) }
 ```
 
-Those two lambdas are the whole integration for a multi-tenant app.
-
 ### Signing in
 
 ```ruby
-class UrisController < ApplicationController
+class DashboardController < ApplicationController
   include Masks::Rails::Authentication
 
   before_action :authenticate_masks!
@@ -65,18 +62,16 @@ class UrisController < ApplicationController
 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
-backend-for-frontend pattern, and it is the default because an SPA holding a token is an
-SPA where XSS lifts one.
+`masks_identity`, `masks_tenant`, and `masks_scopes` describe the signed-in request. Tokens live in
+the encrypted Rails session and never reach JavaScript.
 
-The include is **not** blanket. `config.authenticate_everything = true` puts it on every
-controller if that is what you want; otherwise include it where you mean it.
+`config.authenticate_everything = true` includes `Authentication` on every controller. Otherwise
+include it where it applies.
 
-### An SPA in front of it
+### A single-page app in front of it
 
-`GET /auth/session` answers identity, tenant and scopes as JSON, or `401` with somewhere
-to send the browser. [`@masks/client`](https://masks.pages.dev/reference/browser/) speaks it:
+`GET /auth/session` answers identity, tenant, and scopes as JSON, or `401` with where to send the
+browser. [`@masks/client`](https://masks.pages.dev/reference/browser/) reads it:
 
 ```js
 import { createSession } from "@masks/client"
@@ -85,9 +80,8 @@ const session = createSession()
 const status = await session.status()
 ```
 
-`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.
+`status()` answers `signed_in`, `signed_out` with where to sign in, or `handshake_required` with
+where to connect the app first.
 
 ### Accepting tokens
 
@@ -97,22 +91,25 @@ An app that is also a resource server:
 class ApiController < ApplicationController
   include Masks::Rails::ProtectedResource
 
-  masks_protect! scope: "uris:catalog:read"
+  masks_protect! scope: "xixo:catalog:read", except: :metadata
+
+  def metadata
+    render json: masks_resource_metadata
+  end
 end
 ```
 
-`masks_protect!` is a class method that installs the `before_action` itself, and passes `:only` and
-`:except` through.
-
+`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
-`resource_metadata`, so a client handed nothing but a URL can find its way to the issuer
-and back.
+`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).
 
 ### Organizations
 
 A person signs in to an app as a member of one organization when the app asks for the
 `organization` scope. Someone in several organizations picks one, and an app can pick for them by
-naming it: `/auth?organization=acme`, or `config.organization` for every sign-in.
+naming it, with `/auth?organization=acme` or with `config.organization` for every sign-in.
 
 ```ruby
 Masks::Rails.configure do |config|
@@ -147,38 +144,37 @@ in to none and `insufficient_role` when they hold another role. A resource serve
 token:
 
 ```ruby
-masks_protect! scope: "uris:catalog:write", role: "owner", organization: "acme"
+masks_protect! scope: "xixo:catalog:write", role: "owner", organization: "acme"
 ```
 
 Naming an organization without asking for the scope still holds the sign-in to its members and its
-sign-in policy; the app just learns nothing about the role.
+sign-in policy, and the app learns nothing about the role.
 
 ### 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.
+Every account has three avatars: an uploaded `photo`, an `identicon`, and two-letter `initials`.
+All three arrive on the ID token.
 
 ```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:
+A photo needs a token, which an `<img>` cannot carry, so the engine proxies it with the token the
+app 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.
+`masks_claims.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.
 
 ### Signing out
 
-`DELETE /auth/logout` ends this app's session. Add `?everywhere=1` and the response
-carries `logout_url` — the issuer's end-session endpoint — so signing out can mean
-signing out. `config.sign_out_of_issuer = true` makes that the default for every
-sign-out.
+`DELETE /auth/logout` ends this app's session and revokes its refresh token at the issuer. With `?everywhere=1` the response also carries
+`logout_url`, the issuer's end-session endpoint. `config.sign_out_of_issuer = true` makes that the
+default for every sign-out.
 
 ### Configuration
 
@@ -188,22 +184,23 @@ a subdomain-per-tenant host needs.
 | | |
 |---|---|
 | `issuer` | the masks issuer this app signs in against |
-| `resource` | this app's own identifier, when it also accepts tokens |
+| `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; defaults to `openid profile email` |
+| `scope` | what to ask the issuer for, `openid profile email` by default |
 | `organization` | the organization every sign-in names, by key |
 | `credentials` / `store` | where the handshake's result lives |
-| `credentials_path` | where the default store writes; `config/masks.json` |
+| `manages` | who may reconnect or disconnect a connected app |
+| `credentials_path` | where the default store writes, `config/masks.json` by default |
 | `after_sign_in` / `after_sign_out` | paths on this host |
 | `parent_controller` | what the engine's pages inherit, for your layout |
 | `authenticate_everything` | include `Authentication` on every controller |
 | `sign_out_of_issuer` | make every sign-out an RP-initiated logout |
 | `session_key` | the session key the tokens live under |
+| `delegates` / `delegation_redirect_uri` | ask for delegation in the handshake, and where connecting an account returns |
 
 ## Any Ruby app
 
-Everything above is `Masks::Client` underneath, and it is usable directly — the engine
-holds no protocol of its own.
+The Rails engine is built on `Masks::Client`, which any Ruby app can use directly.
 
 ### The consumer half
 
@@ -215,22 +212,22 @@ session = Masks::Client::Session.new(
 )
 
 started = session.start(resource: "https://app.example.com/mcp")
-# hold started[:state], started[:nonce] and started[:verifier]; send the
-# browser to started[:url]
 
 tokens = session.complete(code: params[:code], verifier: held[:verifier])
 identity = session.identity(tokens)
 ```
 
-`start` sends a nonce only when `openid` was asked for, so holding one means an id token
-is owed, and the check on the way back is exact.
+Hold `started[:state]`, `started[:nonce]`, and `started[:verifier]` in the session, and send the
+browser to `started[:url]`. `start` sends a nonce only when the scope includes `openid`. Check the
+returned `state` yourself, and compare `identity["nonce"]` with the one you held.
 
-Also: `refresh`, `exchange`, `revoke`, `introspect`, `userinfo`, and `end_session_url`.
+`Session` also has `refresh`, `exchange`, `client_credentials`, `revoke`, `introspect`, `userinfo`,
+and `end_session_url`. It authenticates with `client_secret`, or with `private_key` and `key_id` for
+`private_key_jwt`.
 
-Discovery and JWKS are cached for five minutes, with invalidate-and-refetch on an unknown
-`kid`, so a key rotation is picked up without a restart. The cache is real only if the
-`Issuer` is: use `Masks::Client::Issuer.resolve`, or the registry behind it, rather than
-constructing one per request.
+Discovery and JWKS are cached for five minutes and refetched on an unknown `kid`, so a key rotation
+needs no restart. The cache lives on the `Issuer`, so use `Masks::Client::Issuer.resolve` instead
+of constructing one per request.
 
 ### The handshake
 
@@ -238,17 +235,18 @@ 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/"
 )
 
-started = handshake.start          # hold started[:state]; send the browser on
+started = handshake.start
 registration = handshake.complete(params, state: held)
 ```
 
-`complete` refuses an `error`, a `state` that does not match this browser, and an `iss`
-that is not the issuer it asked — each **before** anything is redeemed.
+Hold `started[:state]` and send the browser to `started[:url]`. Before it redeems anything,
+`complete` refuses an `error`, a `state` that does not match this browser, and an `iss` other than
+the issuer it asked.
 
 ### The resource-server half
 
@@ -256,51 +254,58 @@ that is not the issuer it asked — each **before** anything is redeemed.
 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")
+claims = resource.authenticate(
+  request.authorization, scope: "xixo:catalog:read",
+  proof: request.get_header("HTTP_DPOP"), method: request.request_method, url: request.url
+)
 claims.subject
 claims.tenant.subdomain
 ```
 
-`authenticate` answers `Claims` or raises. A refusal builds the RFC 6750 challenge
-carrying `resource_metadata` and the scopes it would have accepted:
+`authenticate` answers `Claims` or raises. A token bound to a key with DPoP carries `cnf.jkt`, and is
+accepted only as `Authorization: DPoP` with a proof signed by that key for this method, URL, and
+token, made within the last minute and never seen before. `proof`, `method`, and `url` are what it
+checks the proof against. Seen proofs are kept in the process's memory. A deployment with several
+processes passes `replay:` to `Resource.new`, any object whose `first?(key, expires_in:)` answers true
+only once for each key.
+
+A refusal builds the RFC 6750 challenge carrying `resource_metadata` and the scopes it would have
+accepted:
 
 ```ruby
 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 `uris:catalog:read` means.
+`resource.metadata` is the RFC 9728 document to serve at `/.well-known/oauth-protected-resource`.
+Its `scope_descriptions` extension gives masks the sentences its consent screen shows for each
+scope.
 
-There is a Rack middleware for consumers that want the challenge below the framework:
+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
 
-A resource server doing JWT-only validation cannot see a revocation until the token
-expires. Ask the issuer instead:
+A resource server that only verifies the JWT sees a revocation when the token expires. Introspection
+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!` raises when the issuer says the token is
-not active, so moving from local verification to introspection needs no extra boolean
-check.
+`Introspection` is a `Claims` whose `permit!` also raises when the token is not active.
 
 ### 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
+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/guides/connecting-via-sdk/#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
@@ -326,9 +331,9 @@ A Rails app sets `config.delegates = true`, so its handshake asks for `masks:del
 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.
+has to connect again, and `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, because spending one
+twice revokes it.
 
 Tests use the fake, which needs no issuer:
 
@@ -344,16 +349,10 @@ 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 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.
+The full reference is generated from this gem at [masks.pages.dev](https://masks.pages.dev): `ruby`
+for `Masks::Client` and `rails` for the engine.
 
 ## License
 

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

@@ -2,6 +2,7 @@ module Masks
   module Rails
     class HandshakesController < BaseController
       before_action :require_unconfigured_or_signed_in
+      before_action :require_unconfigured_or_manager
 
       def show
         return begin! unless masks_config.configured?(request)
@@ -69,6 +70,16 @@ module Masks
           redirect_to masks_config.after_sign_out
         end
 
+        def require_unconfigured_or_manager
+          return unless masks_config.configured?(request)
+          return if masks_config.manages?(request, masks_identity)
+
+          @code = "forbidden"
+          @description = "only somebody this app lets manage its connection can reconnect or disconnect it"
+
+          render :refused, status: :forbidden
+        end
+
         def stale
           @code = "invalid_state"
           @description = "that connection request is not one this browser started, or it expired"

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

@@ -1,6 +1,9 @@
 module Masks
   module Rails
     class SessionsController < BaseController
+      RESTARTED = "masks_restarted_at".freeze
+      RESTART_WITHIN = 60
+
       def show
         if masks_configured? && (masks_signed_in? || (masks_tokens && masks_refresh!))
           response.headers["Cache-Control"] = "no-store"
@@ -36,8 +39,8 @@ module Masks
       def callback
         pending = masks_requests.claim(params[:state])
 
-        return stale if pending.nil?
         return refuse(params[:error], params[:error_description], pending) if params[:error].present?
+        return stale if pending.nil?
 
         tokens = masks_session.complete(
           code: params[:code],
@@ -55,6 +58,7 @@ module Masks
           return refuse("invalid_nonce", "the id token was issued for another request", pending)
         end
 
+        renew_session
         masks_store(tokens, identity: identity)
 
         redirect_to pending[:return_to] || masks_config.after_sign_in
@@ -70,7 +74,9 @@ module Masks
         everywhere = masks_config.sign_out_of_issuer || params[:everywhere].present?
         upstream = everywhere ? masks_logout_url : nil
 
+        revoke_refresh_token
         masks_forget
+        reset_session
 
         if masks_wants_json?
           render json: { "signed_in" => false, "logout_url" => upstream }.compact
@@ -81,6 +87,23 @@ module Masks
 
       private
 
+        def renew_session
+          carried = session.to_hash.slice(REQUESTS, HANDSHAKES)
+
+          reset_session
+          carried.each { |key, value| session[key] = value }
+        end
+
+        def revoke_refresh_token
+          held = masks_tokens&.refresh_token
+
+          return if held.nil? || !masks_configured?
+
+          masks_session.revoke(held, hint: "refresh_token")
+        rescue Masks::Client::Error
+          false
+        end
+
         def requested_return_to
           masks_local_path(params[:return_to])
         end
@@ -95,6 +118,9 @@ module Masks
         end
 
         def stale
+          return redirect_to(masks_config.after_sign_in) if masks_signed_in? || (masks_tokens && masks_refresh!)
+          return restart unless masks_wants_json? || restarted_lately?
+
           answer(
             "invalid_state",
             "that sign-in request is not one this browser started, or it expired",
@@ -102,6 +128,15 @@ module Masks
           )
         end
 
+        def restart
+          session[RESTARTED] = Time.now.to_i
+          redirect_to start_path
+        end
+
+        def restarted_lately?
+          Time.now.to_i - session[RESTARTED].to_i < RESTART_WITHIN
+        end
+
         def refuse(code, description, pending = nil)
           masks_forget if pending
 

data/lib/masks/client/errors.rb

@@ -29,13 +29,18 @@ module Masks
     class Challenge < Error
       attr_reader :code, :description, :status, :scope
 
-      def initialize(code, description, status:, scope: nil)
+      def initialize(code, description, status:, scope: nil, dpop: false)
         super([ code, description ].compact.join(": "))
 
         @code = code
         @description = description
         @status = status
         @scope = scope
+        @dpop = dpop
+      end
+
+      def dpop?
+        @dpop
       end
     end
 
@@ -46,8 +51,8 @@ module Masks
     end
 
     class Unauthorized < Challenge
-      def initialize(description, code: "invalid_token")
-        super(code, description, status: 401)
+      def initialize(description, code: "invalid_token", dpop: false)
+        super(code, description, status: 401, dpop: dpop)
       end
     end
 

data/lib/masks/client/pkce.rb

@@ -14,9 +14,7 @@ module Masks
       end
 
       def challenge
-        Base64.urlsafe_encode64(
-          OpenSSL::Digest::SHA256.digest(verifier), padding: false
-        )
+        Proof.digest(verifier)
       end
 
       def method

data/lib/masks/client/proof.rb

@@ -0,0 +1,153 @@
+module Masks
+  module Client
+    class Proof
+      class Invalid < Error; end
+
+      SCHEME = "DPoP".freeze
+      TYPE = "dpop+jwt".freeze
+      ALGORITHMS = %w[ES256 ES384 ES512 PS256 PS384 PS512 RS256].freeze
+      SECRET = %w[d p q dp dq qi k].freeze
+      THUMBED = { "EC" => %w[crv kty x y], "RSA" => %w[e kty n] }.freeze
+      LEEWAY = 30
+      WINDOW = 60
+      MEMORY = WINDOW + (LEEWAY * 2)
+
+      class Memory
+        def initialize
+          @held = {}
+          @lock = Mutex.new
+          @swept = 0.0
+        end
+
+        def first?(key, expires_in:)
+          now = Time.now.to_f
+
+          @lock.synchronize do
+            sweep(now) if now - @swept > 1
+            return false if @held.key?(key) && @held[key] >= now
+
+            @held[key] = now + expires_in
+            true
+          end
+        end
+
+        private
+
+          def sweep(now)
+            @held.delete_if { |_, until_at| until_at < now }
+            @swept = now
+          end
+      end
+
+      MEMORY_LOCK = Mutex.new
+
+      def self.memory
+        MEMORY_LOCK.synchronize { @memory ||= Memory.new }
+      end
+
+      def self.thumbprint(jwk)
+        named = THUMBED[jwk["kty"]] || raise(Invalid, "the proof key is of a kind this resource does not read")
+        held = named.to_h { |field| [ field, jwk[field] ] }
+
+        raise Invalid, "the proof key is missing part of itself" if held.any? { |_, value| value.to_s.empty? }
+
+        digest(JSON.generate(held))
+      end
+
+      def self.digest(value)
+        Base64.urlsafe_encode64(OpenSSL::Digest::SHA256.digest(value.to_s), padding: false)
+      end
+
+      def initialize(proof, method:, url:, replay: nil)
+        held = proof.to_s.split(",").map(&:strip).reject(&:empty?)
+
+        raise Invalid, "exactly one DPoP proof is required" unless held.size == 1
+
+        @proof = held.first
+        @method = method.to_s.upcase
+        @url = url.to_s
+        @replay = replay
+      end
+
+      def check!(access_token:, jkt:)
+        header = keyed
+        claims = verified(header)
+        thumbprint = self.class.thumbprint(header["jwk"])
+
+        raise Invalid, "that proof was made with another key than the token is bound to" unless same?(thumbprint, jkt)
+
+        matches!(claims)
+        timely!(claims)
+        raise Invalid, "that proof was made for another token" unless same?(claims["ath"].to_s, self.class.digest(access_token))
+
+        once!(claims, thumbprint)
+
+        self
+      end
+
+      private
+
+        def keyed
+          header = JWT.decode(@proof, nil, false).last
+
+          raise Invalid, "a proof must be typed #{TYPE}" unless header["typ"].to_s.casecmp?(TYPE)
+          raise Invalid, "#{header['alg'] || 'that'} is not an algorithm a proof may use" unless ALGORITHMS.include?(header["alg"].to_s)
+
+          jwk = header["jwk"]
+
+          raise Invalid, "a proof must carry the public key that signed it" unless jwk.is_a?(Hash)
+          raise Invalid, "a proof key must be public" if jwk["kty"].to_s == "oct" || jwk.keys.any? { |field| SECRET.include?(field.to_s) }
+
+          header
+        rescue JWT::DecodeError
+          raise Invalid, "that proof is not a readable JWT"
+        end
+
+        def verified(header)
+          JWT.decode(@proof, JWT::JWK.new(header["jwk"]).verify_key, true,
+                     algorithms: [ header["alg"].to_s ], verify_expiration: false).first
+        rescue JWT::DecodeError, JWT::JWKError, OpenSSL::PKey::PKeyError, ArgumentError
+          raise Invalid, "that proof was not signed by the key it carries"
+        end
+
+        def matches!(claims)
+          raise Invalid, "that proof was made for another method" unless claims["htm"].to_s.upcase == @method
+          raise Invalid, "that proof was made for another URL" unless tidied(claims["htu"]) == tidied(@url)
+        end
+
+        def tidied(value)
+          uri = URI.parse(value.to_s)
+          raise Invalid, "that proof names no URL" if uri.host.nil?
+
+          port = ":#{uri.port}" unless uri.port.nil? || uri.port == uri.default_port
+          path = uri.path.to_s == "/" ? "" : uri.path.to_s
+
+          "#{uri.scheme.to_s.downcase}://#{uri.host.downcase}#{port}#{path}"
+        rescue URI::InvalidURIError
+          raise Invalid, "that proof names a URL this resource cannot read"
+        end
+
+        def timely!(claims)
+          made = claims["iat"]
+
+          raise Invalid, "a proof must say when it was made" unless made.is_a?(Numeric)
+          raise Invalid, "that proof was made too long ago" if made < Time.now.to_i - WINDOW - LEEWAY
+          raise Invalid, "that proof was made in the future" if made > Time.now.to_i + LEEWAY
+        end
+
+        def once!(claims, thumbprint)
+          jti = claims["jti"].to_s
+
+          raise Invalid, "a proof must carry a jti" if jti.empty?
+          return if @replay.nil? || @replay.first?("#{thumbprint}:#{jti}", expires_in: MEMORY)
+
+          raise Invalid, "that proof has already been used"
+        end
+
+        def same?(held, expected)
+          !held.to_s.empty? && held.bytesize == expected.to_s.bytesize &&
+            OpenSSL.fixed_length_secure_compare(held, expected.to_s)
+        end
+    end
+  end
+end

data/lib/masks/client/rack.rb

@@ -15,7 +15,10 @@ module Masks
       def call(env)
         return @app.call(env) unless guards?(env)
 
-        env[CLAIMS] = resource(env).authenticate(env["HTTP_AUTHORIZATION"], scope: @scope)
+        env[CLAIMS] = resource(env).authenticate(
+          env["HTTP_AUTHORIZATION"], scope: @scope,
+          proof: env["HTTP_DPOP"], method: env["REQUEST_METHOD"], url: url(env)
+        )
 
         @app.call(env)
       rescue Challenge => e
@@ -32,6 +35,17 @@ module Masks
           @only.call(env)
         end
 
+        def url(env)
+          if defined?(::Rack::Request)
+            request = ::Rack::Request.new(env)
+            return "#{request.base_url}#{request.path}"
+          end
+
+          host = env["HTTP_HOST"] || "#{env['SERVER_NAME']}:#{env['SERVER_PORT']}"
+
+          "#{env['rack.url_scheme'] || 'http'}://#{host}#{env['SCRIPT_NAME']}#{env['PATH_INFO']}"
+        end
+
         def passthrough(env, error)
           env[ERROR] = error
 

data/lib/masks/client/registry.rb

@@ -16,10 +16,6 @@ module Masks
         @lock.synchronize { @issuers.clear }
         self
       end
-
-      def urls
-        @lock.synchronize { @issuers.keys }
-      end
     end
   end
 end

data/lib/masks/client/resource.rb

@@ -1,14 +1,14 @@
 module Masks
   module Client
     class Resource
-      BEARER = /\ABearer[ \t]+([^\s,]+)[ \t]*\z/i.freeze
+      PRESENTED = /\A(Bearer|DPoP)[ \t]+([^\s,]+)[ \t]*\z/i.freeze
       METADATA_PATH = "/.well-known/oauth-protected-resource".freeze
       REQUIRED = %w[iss sub exp].freeze
 
       attr_reader :issuer, :url, :scopes
 
       def initialize(issuer:, url:, scopes: [], metadata_url: nil,
-                     algorithms: Verifier::ALGORITHMS, required: REQUIRED, verifier: nil)
+                     algorithms: Verifier::ALGORITHMS, required: REQUIRED, verifier: nil, replay: Proof.memory)
         @issuer = Issuer.resolve(issuer)
         @url = url.to_s
         @descriptions = describe(scopes)
@@ -16,10 +16,14 @@ module Masks
         @metadata_url = metadata_url
         @required = Array(required)
         @verifier = verifier || Verifier.new(@issuer, audience: @url, algorithms: algorithms)
+        @replay = replay
       end
 
-      def authenticate(authorization, scope: nil, role: nil, organization: nil)
-        claims = Claims.new(@verifier.verify(token!(authorization), required: @required, typ: Verifier::ACCESS_TOKEN))
+      def authenticate(authorization, scope: nil, role: nil, organization: nil, proof: nil, method: nil, url: nil)
+        scheme, token = presented!(authorization)
+        held = @verifier.verify(token, required: @required, typ: Verifier::ACCESS_TOKEN)
+        bound!(held, scheme, token, proof: proof, method: method, url: url)
+        claims = Claims.new(held)
 
         Array(scope).each { |name| claims.permit!(name) }
         claims.member!(*Array(role), organization: organization) if role || organization
@@ -30,7 +34,7 @@ module Masks
       end
 
       def token(authorization)
-        authorization.to_s[BEARER, 1]
+        authorization.to_s[PRESENTED, 2]
       end
 
       def metadata_url
@@ -43,7 +47,8 @@ module Masks
           "authorization_servers" => [ issuer.url ],
           "scopes_supported" => scopes,
           "scope_descriptions" => @descriptions,
-          "bearer_methods_supported" => [ "header" ]
+          "bearer_methods_supported" => [ "header" ],
+          "dpop_signing_alg_values_supported" => Proof::ALGORITHMS
         }.reject { |_, value| value.respond_to?(:empty?) && value.empty? }
       end
 
@@ -57,7 +62,9 @@ module Masks
           [ "resource_metadata", metadata_url ]
         ]
 
-        "Bearer " + parameters.filter_map { |name, value|
+        scheme = error.dpop? ? "#{Proof::SCHEME} algs=\"#{Proof::ALGORITHMS.join(' ')}\", " : "Bearer "
+
+        scheme + parameters.filter_map { |name, value|
           %(#{name}="#{quote(value)}") if value && !value.to_s.empty?
         }.join(", ")
       end
@@ -72,8 +79,22 @@ module Masks
           end.freeze
         end
 
-        def token!(authorization)
-          token(authorization) || raise(Unauthenticated.new)
+        def presented!(authorization)
+          match = authorization.to_s.match(PRESENTED) || raise(Unauthenticated.new)
+
+          [ match[1].casecmp?(Proof::SCHEME) ? :dpop : :bearer, match[2] ]
+        end
+
+        def bound!(claims, scheme, token, proof:, method:, url:)
+          jkt = claims.dig("cnf", "jkt")
+
+          raise Unauthorized.new("that token is not bound to a key, so it is presented as Bearer") if jkt.nil? && scheme == :dpop
+          raise Unauthorized.new("that token is bound to a key, so it is presented as DPoP with a proof", dpop: true) if jkt && scheme != :dpop
+          return if jkt.nil?
+
+          Proof.new(proof, method: method, url: url || self.url, replay: @replay).check!(access_token: token, jkt: jkt)
+        rescue Proof::Invalid => e
+          raise Unauthorized.new(e.message, code: "invalid_dpop_proof", dpop: true)
         end
 
         def origin

data/lib/masks/client/verifier.rb

@@ -32,10 +32,6 @@ module Masks
         raise InvalidToken, e.message
       end
 
-      def tenant(token)
-        verify(token)["tenant"]
-      end
-
       private
 
         def typed!(held, accepted)

data/lib/masks/client.rb

@@ -19,6 +19,7 @@ require_relative "client/claims"
 require_relative "client/introspection"
 require_relative "client/session"
 require_relative "client/verifier"
+require_relative "client/proof"
 require_relative "client/logout"
 require_relative "client/resource"
 require_relative "client/rack"

data/lib/masks/rails/authentication.rb

@@ -318,9 +318,15 @@ module Masks
           path = value.to_s
 
           return nil unless path.start_with?("/")
-          return nil if path.start_with?("//", "/\\")
+          return nil if path.match?(/[\x00-\x20\x7f\\]/)
 
-          path
+          uri = URI.parse(path)
+
+          return nil if uri.scheme || uri.host || uri.userinfo || !uri.path.start_with?("/") || uri.path.start_with?("//")
+
+          [ uri.path, uri.query ].compact.join("?")
+        rescue URI::InvalidURIError
+          nil
         end
     end
   end

data/lib/masks/rails/configuration.rb

@@ -7,7 +7,7 @@ module Masks
                     :after_sign_out, :session_key, :sign_out_of_issuer, :parent_controller,
                     :credentials_path, :authenticate_everything, :delegates
       attr_writer :issuer, :redirect_uri, :name, :credentials, :store, :forget, :logged_out,
-                  :delegation_redirect_uri, :organization
+                  :delegation_redirect_uri, :organization, :manages
 
       def initialize
         @scope = Masks::Client::Session::DEFAULT_SCOPE
@@ -89,6 +89,14 @@ 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
+      end
+
       def can_forget?
         @forget.respond_to?(:call) || !@store.respond_to?(:call)
       end
@@ -106,19 +114,6 @@ module Masks
         @store.call(request, registration)
       end
 
-      MINIMUM_ISSUER = 1
-
-      def issuer_speaks!(request)
-        spoken = Masks::Client::Issuer.resolve(issuer_for(request))
-                                     .discovery["masks_protocol_version"].to_i
-
-        return true if spoken >= MINIMUM_ISSUER
-
-        raise Unconfigured,
-              "#{issuer_for(request)} speaks masks protocol #{spoken}, and masks " \
-              "#{Masks::VERSION} needs at least #{MINIMUM_ISSUER}"
-      end
-
       def session_for(request)
         raise Unconfigured, "this app has not shaken hands with #{issuer_for(request)}" unless configured?(request)
 

data/lib/masks/rails/protected_resource.rb

@@ -20,18 +20,23 @@ module Masks
 
       def masks_authenticate!(scope: nil, role: nil, organization: nil, **)
         @masks_claims = masks_resource.authenticate(request.authorization, scope: scope, role: role,
-                                                                           organization: organization)
+                                                                           organization: organization, **masks_proof)
       rescue Masks::Client::Challenge => e
         masks_challenge(e)
         false
       end
 
       def masks_authenticate(scope: nil, role: nil, organization: nil)
-        masks_resource.authenticate(request.authorization, scope: scope, role: role, organization: organization)
+        masks_resource.authenticate(request.authorization, scope: scope, role: role, organization: organization,
+                                                           **masks_proof)
       rescue Masks::Client::Unauthenticated
         nil
       end
 
+      def masks_proof
+        { proof: request.headers["DPoP"], method: request.request_method, url: "#{request.base_url}#{request.path}" }
+      end
+
       def masks_challenge(error)
         error = Masks::Client::Unauthorized.new(error.to_s) unless error.is_a?(Masks::Client::Challenge)
 

data/lib/masks/version.rb

@@ -1,3 +1,3 @@
 module Masks
-  VERSION = "0.8.0".freeze
+  VERSION = "0.9.2".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: masks
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.2
 platform: ruby
 authors:
 - the masks authors
@@ -57,6 +57,7 @@ files:
 - lib/masks/client/issuer.rb
 - lib/masks/client/logout.rb
 - lib/masks/client/pkce.rb
+- lib/masks/client/proof.rb
 - lib/masks/client/rack.rb
 - lib/masks/client/registration.rb
 - lib/masks/client/registry.rb