masks 0.7.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5da19b0cb3099ebe46f2b4509615a75422fa0b2820abb799e8f182ce11f456ad
-  data.tar.gz: 4d5d6b573cccbca63439587cd3363d22be28dd0d8ff95051f32dcc8252494185
+  metadata.gz: 62fc7998cf31199eaa81f63d82063e3e20ab995c74c782c675e91628df7dcee3
+  data.tar.gz: 6d83a9474d9289c375acfcacd6c5c4e45a66a92d22e1683abba9780de3c63d43
 SHA512:
-  metadata.gz: 130ccd4e8a1ca7ddfe996f7439af4dc800501ea0a81ec0a18561475447931af40affb0cd0e2a66aa191d28d93f677046f49b7d5db6a913426fa21114d1bcbb68
-  data.tar.gz: bd818590edc19a344daf59e755d8657da71e10f2017fc3b8ffe95ed6f8452f804a6ccdc7da621425b288c5934b25b5c39bd41923d13983e16fab9ab144bdfd78
+  metadata.gz: 97164bf9ab0ee6820e353a9dad5d97141ddf0cd038dd3a6348e03e46eea46313643e13f8d49c17bd414c16420e4b25c5c29072bd4efea114f3483e4174c0e599
+  data.tar.gz: 505cca23a8b1b0f439365eea100780b64157700ab9995df53fa46df640a0efc1da9a64e95281925279233ea4e4036563e41aebd727d8b7f2795991dac3604931

data/CHANGELOG.md

@@ -1,5 +1,66 @@
 # Changelog
 
+## [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)
+
+
+### ⚠ BREAKING CHANGES
+
+* a resource server on an older gem still accepts the new tokens, but this gem refuses access tokens from a server that does not type them.
+
+### Features
+
+* an access token is typed at+jwt, and nothing takes a token of another type in its place ([d0b4cfd](https://github.com/masksrb/masks/commit/d0b4cfdf802053359695495d417225e3a1578302))
+* **client:** a Rails app lists the organizations a person belongs to and links them to another ([7f0d223](https://github.com/masksrb/masks/commit/7f0d2237799e04551d2c403de695c704e5455db8))
+* **client:** a Rails app names the organization a person signs in to, reads their role, and keeps pages and APIs to members in a role ([579cecc](https://github.com/masksrb/masks/commit/579ceccac1c0137dfa1ed7a3894dea61e5cdd67e))
+* **client:** a session signs its own client assertions, and asks for a token of its own ([614248b](https://github.com/masksrb/masks/commit/614248b70a3ee517fbd3c1f7151b66ec6406b487))
+* **client:** an exchange hands over an ID token or an actor token ([6b67766](https://github.com/masksrb/masks/commit/6b67766ce275b9578d575349256638adddd5a599))
+* **client:** the session says where the person manages their account, as account_url ([1d36e1d](https://github.com/masksrb/masks/commit/1d36e1d4daa8c5acfc9133a1896aa9384771dbd6))
+
+
+### Documentation
+
+* Rails apps covers client, server, and engine mode ([41454a2](https://github.com/masksrb/masks/commit/41454a242438e4df246dcbc4dce94b6d8a022239))
+
+
+### Refactoring
+
+* **client:** an organization key is checked in one place, and a refresh renews the whole identity from userinfo ([b349aae](https://github.com/masksrb/masks/commit/b349aaec4dd5c9790c72dd1dc8f91016a2adceea))
+
 ## [0.7.0](https://github.com/masksrb/masks/compare/gem/v0.6.0...gem/v0.7.0) (2026-09-13)
 
 

data/README.md

@@ -1,4 +1,4 @@
-<p align="center"><img src="https://raw.githubusercontent.com/masksrb/masks/main/server/public/icon.svg" width="120" alt="The masks rose window"></p>
+<p align="center"><img src="https://raw.githubusercontent.com/masksrb/masks/main/engine/public/masks-public/icon.svg" width="120" alt="The masks rose window"></p>
 
 # masks
 
@@ -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,43 +91,90 @@ An app that is also a resource server:
 class ApiController < ApplicationController
   include Masks::Rails::ProtectedResource
 
-  masks_protect! scope: "uris:catalog:read"
+  masks_protect! scope: "uris: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, with `/auth?organization=acme` or with `config.organization` for every sign-in.
+
+```ruby
+Masks::Rails.configure do |config|
+  config.scope = %w[openid profile email offline_access organization]
+  config.organization = ->(request) { request.subdomain }
+end
+
+class BillingController < ApplicationController
+  include Masks::Rails::Authentication
+
+  masks_members_only! role: %w[owner 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
+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
+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| %>
+  <%= 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"
+```
+
+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.
 
 ### 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
 
@@ -143,21 +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
 
@@ -169,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
 
@@ -197,12 +240,13 @@ handshake = Masks::Client::Handshake.new(
   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
 
@@ -213,24 +257,33 @@ resource = Masks::Client::Resource.new(
   scopes: { "uris:catalog:read" => "Search your catalog" }
 )
 
-claims = resource.authenticate(request.authorization, scope: "uris:catalog:read")
+claims = resource.authenticate(
+  request.authorization, scope: "uris: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"
@@ -238,23 +291,21 @@ 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. 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")
 ```
 
-`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
@@ -280,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:
 
@@ -298,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"
@@ -21,7 +24,9 @@ module Masks
         )
         started = masks_session.start(
           state: pending.id,
-          resource: masks_config.resource_for(request)
+          resource: masks_config.resource_for(request),
+          organization: Masks::Client::Session.organization_key(params[:organization]) ||
+            masks_config.organization_for(request)
         )
 
         masks_requests.amend(
@@ -34,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],
@@ -53,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
@@ -68,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
@@ -79,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
@@ -93,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",
@@ -100,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