masks 0.10.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c0b13e1f370033e4c4512becb39b4d96e4b9d28b39b7f1e773592138626d1151
-  data.tar.gz: 8540eeecb1b448047198d5da57e5978d0e4ec249138334e7c39d41a719854a99
+  metadata.gz: 22811283549c975e2550ab8546760831275db1efa68ddfd16ebe1dcfb96278a5
+  data.tar.gz: 888decf6ea332f751cb446a4e7535313527141ed64086cbf62acc2787d320a9b
 SHA512:
-  metadata.gz: fc1b4981446fdc5282e21c00c93a63cbc124d3c675512172a849cdd698f0a52839fce8098fdde6443814131f198eef5829d1dd52416e02bb51ef95f7d5fb634a
-  data.tar.gz: e40f6519f1c22fefa134217cff31701617551feed13e374f1d801307c2f021cb21eba5b85adc4eb9d28e133e855c4aad4cc05caa4749d34fadd9d7e833493cc1
+  metadata.gz: 33275896c9010d94818885f7a0a3f71b83f6782af7384cf29fb70d482b03492b8e662f27d6f748e1d9a05f453f5294dc910ca5d1492395c7bc3e0bc57aaaea6f
+  data.tar.gz: 5fb2c1d80a01a0723c3533bc8861cca4c2d0761e9ef5d4ef21f46de41d611835bf9fefe28ac0bab860b65bb0ee166cf8288fbda1a178644f58dc3a850edaea96

data/CHANGELOG.md

@@ -1,5 +1,68 @@
 # Changelog
 
+## [0.12.0](https://github.com/masksrb/masks/compare/gem/v0.11.0...gem/v0.12.0) (2026-10-14)
+
+
+### Features
+
+* **client:** config.cache shares refreshes, back-channel logouts, and DPoP proofs across a Rails app's processes ([1019324](https://github.com/masksrb/masks/commit/1019324f74d44aa9df62d860082c529f5effda44))
+
+
+### Fixes
+
+* **client:** a back-channel logout token must carry exp, and its jti is remembered until two minutes after it expires ([ffbf534](https://github.com/masksrb/masks/commit/ffbf53485583d342f0d6e147077b0c7df05c911f))
+* **client:** a cache outage is told apart from a repeat, so masks and DPoP clients get 503 instead of a refusal ([8884cb6](https://github.com/masksrb/masks/commit/8884cb680e802521a413ea17a96eedfec58cae35))
+* **client:** a page on another site can no longer sign somebody out of a Rails app ([96a084f](https://github.com/masksrb/masks/commit/96a084fe0172b27c1affe9461199335fe2b1bbba))
+* **client:** a Rails sign-in keeps its tokens in its own cookies, split across up to eight, so a large access token no longer overflows the session ([88325fb](https://github.com/masksrb/masks/commit/88325fbee0d54bd90ffe3e7286dfa1553582ff2d))
+* **client:** a sign-in callback this browser did not start no longer repeats the error text in its URL ([60574f2](https://github.com/masksrb/masks/commit/60574f263f11420933956354f3e1cae222cf0418))
+* **client:** HTTP.fetch reads at most 8 MB, so the avatar proxy cannot be made to hold an endless answer ([541c0b5](https://github.com/masksrb/masks/commit/541c0b56d648d8bee2eb7cb82ca5ac061adfc350))
+* **client:** signing out of masks returns to /auth/logout/return, which the handshake registers as the app's post-logout address ([d1dbc05](https://github.com/masksrb/masks/commit/d1dbc05e6bcbe41a4143b1efde901495dd6dbcae))
+* **client:** the challenge for a request with no token carries no error description ([b030959](https://github.com/masksrb/masks/commit/b030959d6fd1b2e32be7f8173b17cde4282d43cc))
+* **engine:** a handshake registers only the post-logout address it names, and keeps its return_to apart, so a new return_to is still asked about ([47a8988](https://github.com/masksrb/masks/commit/47a898874ee2c00f9763a57624cc3cb207a7e48f))
+* **engine:** a refused token is described in masks' own words, not the JWT library's ([dae249d](https://github.com/masksrb/masks/commit/dae249d348c65e83bf96f680746d60ba4642c58d))
+
+
+### Documentation
+
+* **client:** the to-do list records how close a Rails session sits to the cookie limit ([deedb14](https://github.com/masksrb/masks/commit/deedb144ba9458904348fa7482303d21691aefbf))
+* comments and pages no longer claim what masks stopped doing ([e0b1ba0](https://github.com/masksrb/masks/commit/e0b1ba0b71ccae8683b605f9442ee16c4afb5dd4))
+* every guide, SDK reference, and README says what masks does now, in fewer words ([7046f86](https://github.com/masksrb/masks/commit/7046f862c774f05407d92cd19779f53bf0b62595))
+
+
+### Refactoring
+
+* **client:** HTTP.fetch is a GET through deliver with no read limit, and an embedded request's Host comes from Nonces.origin ([0398e13](https://github.com/masksrb/masks/commit/0398e135ba1a41fd56007709bb35aef900f14e57))
+
+## [0.11.0](https://github.com/masksrb/masks/compare/gem/v0.10.0...gem/v0.11.0) (2026-10-13)
+
+
+### Features
+
+* **client:** a session holds its tokens to a DPoP key and proves it on every token request ([be3732c](https://github.com/masksrb/masks/commit/be3732cec2873fed75d8c70591f9bb1a2dcfb93c))
+* **client:** a session runs the device flow and polls until somebody approves the code ([cd96836](https://github.com/masksrb/masks/commit/cd96836a9d97049f80b9efcf6eec8335e7650a6a))
+* **client:** config.replay names one store of seen DPoP proofs for every process of a Rails app ([e3baf5a](https://github.com/masksrb/masks/commit/e3baf5a04b652ec2205bbc88004cb37b78ac9b0e))
+* **client:** Masks::Client.embed answers an issuer's requests inside the process, for an app that mounts masks and signs in through it ([7473031](https://github.com/masksrb/masks/commit/74730318cd335a74207b1fea0156b646e61d74c1))
+* **client:** Session#enroll asks masks for an enrollment token that a machine spends once to register its own key ([be52734](https://github.com/masksrb/masks/commit/be52734f7d470140749bf2f2d208d81ca85bc42d))
+* **client:** Session#unenroll archives a machine the app enrolled and revokes its tokens ([2743890](https://github.com/masksrb/masks/commit/2743890063f1e3818f8acb29048bb549f1b94220))
+* **server:** /manage, the sign-in pages, and the docs share one palette and one font stack ([17efe87](https://github.com/masksrb/masks/commit/17efe87c81c14d7541a37292bf58ba242836eca5))
+
+
+### Fixes
+
+* **client:** signing out everywhere returns through the handshake callback masks registered, so masks no longer refuses it ([6eb6e70](https://github.com/masksrb/masks/commit/6eb6e7067d43803f0ac8dcfbc04e2d8057ac2ca0))
+* **client:** the gem speaks only https off loopback, reads at most 1 MB, and answers 503 when its replay store is down ([6c03a43](https://github.com/masksrb/masks/commit/6c03a430a500d3476e018cf650bf093ad2aca102))
+
+
+### Documentation
+
+* each language has a group under Reference, with an overview, a page per framework, and its API reference ([64b7837](https://github.com/masksrb/masks/commit/64b7837e0484d11ddd5b4d926fc4aa800c06ed81))
+* each SDK keeps a TODO of the cleanups, security follow-ups, and testing left from the framework integrations ([4c4353b](https://github.com/masksrb/masks/commit/4c4353b63713700034c78f3d3c0b3b45ac7b50b3))
+
+
+### Refactoring
+
+* **server:** /manage derives its surfaces from the shared palette, and --label folds into --brass ([c00d32b](https://github.com/masksrb/masks/commit/c00d32b821cc99b8cbc2903a7a4c0c08aa2770bd))
+
 ## [0.10.0](https://github.com/masksrb/masks/compare/gem/v0.9.2...gem/v0.10.0) (2026-10-11)
 
 

data/README.md

@@ -2,54 +2,35 @@
 
 # masks
 
-Sign a Ruby or Rails app in against a [masks](https://github.com/masksrb/masks) issuer.
+Sign people in to a Ruby or Rails app with a [masks](https://github.com/masksrb/masks) server, and
+accept the tokens it gives out.
 
-```ruby
-gem "masks"
-```
+The gem has two parts:
 
-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.
+- `Masks::Rails`, a Rails engine that adds sign-in to your app. It loads only when Rails does.
+- `Masks::Client`, plain Ruby for any app. It depends on `jwt` and nothing else.
 
-## Rails
+## Install
 
-```sh
-bin/rails generate masks:install --resource https://app.example.com
+```ruby
+gem "masks"
 ```
 
-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`. [Rails apps](https://masks.pages.dev/guides/rails/) walks through the rest.
-
-### The handshake
-
-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 gem needs Ruby 3.2 or later.
 
-Once an app is connected, only somebody `config.manages` approves can reconnect or disconnect it.
-It names a [privilege](#privileges), or is a callable taking the request, or the request and
-`masked`. The engine refuses everyone when it is unset:
+## Rails
 
-```ruby
-config.manages = :admin
-config.manages = ->(request, masked) { masked.subject == ENV["OWNER_SUB"] }
-```
+1. Run the install generator:
 
-The engine writes what comes back to `config/masks.json`, mode 600. A multi-tenant app keeps it
-somewhere else with two callables:
+   ```sh
+   bin/rails generate masks:install --resource https://app.example.com
+   ```
 
-```ruby
-config.credentials = ->(request) { Tenant.for(request).masks_credentials }
-config.store = ->(request, registration) { Tenant.for(request).connect!(registration) }
-```
+2. Set `MASKS_ISSUER` to the masks server and tenant you sign in against.
+3. Start the app and open `/auth/handshake`.
+4. Approve the app on the masks server.
 
-### Signing in
+Then require a sign-in in a controller:
 
 ```ruby
 class DashboardController < ApplicationController
@@ -58,180 +39,13 @@ class DashboardController < ApplicationController
   masked!
 
   def index
-    @who = masked.name
-  end
-end
-```
-
-`masked` is everything about the signed-in request in one object: `subject`, `name`, `nickname`,
-`email`, `picture`, `avatars`, `tenant`, `organization`, `organizations`, `role?`, `scopes`,
-`privileges`, `privilege?`, `access_token`, and `signed_in?`, with `masked["claim"]` for any other
-claim. In a view it is the same helper. Tokens live in the encrypted Rails session and never reach
-JavaScript.
-
-### Privileges
-
-A privilege names what an action needs: scopes the person holds in masks, a role in the organization
-they signed in to, or both. A list is shorthand for `{ scope: [...] }`.
-
-```ruby
-Masks::Rails.configure do |config|
-  config.privileges = {
-    admin: %w[catalog:admin],
-    billing: { role: %w[owner billing] },
-    acme_admin: { scope: %w[catalog:admin], role: "owner", organization: "acme" }
-  }
-end
-
-class SettingsController < ApplicationController
-  masked!
-  masked! :admin, only: %i[create update destroy]
-end
-```
-
-`masked!` with no privilege needs only a sign-in. A privilege's scopes stay out of every ordinary
-sign-in. When a signed-in person lacks one, the browser goes through masks once to ask for it and
-comes back, and the action answers `403` when masks does not grant it. A missing role or organization
-answers `403` at once. `masked.privilege?(:admin)` and `masked.privileges` tell a view what the sign-in
-holds, and `/auth/session` answers `privileges`. See
-[privileges](https://masks.pages.dev/guides/rails/#privileges).
-
-`config.authenticate_everything = true` includes `Authentication` on every controller. Otherwise
-include it where it applies.
-
-### A single-page app in front of 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"
-
-const session = createSession()
-const status = await session.status()
-```
-
-`status()` answers `signed_in`, `signed_out` with where to sign in, or `handshake_required` with
-where to connect the app first.
-
-### Accepting tokens
-
-An app that is also a resource server:
-
-```ruby
-class ApiController < ApplicationController
-  include Masks::Rails::ProtectedResource
-
-  masked! :read, except: :metadata
-
-  def metadata
-    render json: masks_resource_metadata
+    @name = masked.name
   end
 end
 ```
 
-`masked!` checks a [privilege](#privileges) against the bearer token, here
-`config.privileges = { read: %w[xixo:catalog:read] }`. `masked` reads the verified token. A refusal carries the RFC 6750 challenge with
-`resource_metadata`, which points a client at `/.well-known/oauth-protected-resource`. The engine
-does not route that path, so route it to an action like `metadata` above. A DPoP-bound token is
-accepted only with a valid proof, as in [Masks::Client::Resource](#the-resource-server-half).
-
-### 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
-
-  masked! :billing
-end
-```
-
-`masked.organization` is the organization signed in to (its `id`, `key`, `name`, and `role`), or
-`nil`, and `masked.role?("owner")` asks about the role held in it. A refresh reads the person's
-profile again, so a promotion or demotion reaches the app within an access token's lifetime.
-`/auth/session` answers the same thing as `organization`.
-
-`masked.organizations` lists every organization the person has joined, each with the role held in
-it, and `/auth/session` answers it as `organizations`. Switching sends the person through sign-in
-again naming the other one, which asks nothing more when they are already a member:
-
-```erb
-<% masked.organizations.each do |held| %>
-  <%= link_to held.name, masks_login_url(organization: held.key, return_to: request.path) %>
-<% end %>
-```
-
-A privilege with a role refuses with 403, as `insufficient_organization` when the person signed in
-to none and `insufficient_role` when they hold another role. A resource server asks the same of a
-token with `masked!`.
-
-Naming an organization without asking for the scope still holds the sign-in to its members and its
-sign-in policy, and the app learns nothing about the role.
-
-### Avatars
-
-Every account has three avatars: an uploaded `photo`, an `identicon`, and two-letter `initials`.
-All three arrive on the ID token.
-
-```erb
-<img src="<%= masked.avatars.identicon %>?size=64" width="64" height="64" alt="">
-```
-
-A photo needs a token, which an `<img>` cannot carry, so the engine proxies it with the token the
-app holds:
-
-```erb
-<img src="/auth/avatar" width="64" height="64" alt="">
-```
-
-`masked.picture` is the standard OIDC `picture` claim when the account set one, then the photo,
-then the identicon. `issuer.avatar_url(sub, style:, size:)` builds a URL for a subject this app holds
-no token for. Sizes are 32, 64, 128, 256, or 512.
-
-### Signing 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
-
-Every value that varies per request accepts a callable taking the request, which is what
-a subdomain-per-tenant host needs.
-
-| | |
-|---|---|
-| `issuer` | the masks issuer this app signs in against |
-| `resource` | this app's own identifier, which the handshake registers and tokens name as their audience |
-| `resource_scopes` | what it accepts, published in its RFC 9728 metadata |
-| `scope` | what to ask the issuer for, `openid profile email` by default |
-| `privileges` | named scopes, roles, and organizations that `masked!` checks, none by default |
-| `organization` | the organization every sign-in names, by key |
-| `credentials` / `store` | where the handshake's result lives |
-| `manages` | who may reconnect or disconnect a connected app |
-| `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
 
-The Rails engine is built on `Masks::Client`, which any Ruby app can use directly.
-
-### The consumer half
-
 ```ruby
 session = Masks::Client::Session.new(
   issuer: "https://demo.auth.example.com",
@@ -239,148 +53,21 @@ session = Masks::Client::Session.new(
   redirect_uri: "https://app.example.com/auth/callback"
 )
 
-started = session.start(resource: "https://app.example.com/mcp")
-
-tokens = session.complete(code: params[:code], verifier: held[:verifier])
+started = session.start
+tokens = session.complete(code: params[:code], verifier: started[:verifier])
 identity = session.identity(tokens)
 ```
 
-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.
-
-`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 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
-
-The flow that connects a first-party app:
-
-```ruby
-handshake = Masks::Client::Handshake.new(
-  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
-registration = handshake.complete(params, state: held)
-```
-
-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
-
-```ruby
-resource = Masks::Client::Resource.new(
-  issuer: "https://demo.auth.example.com",
-  url: "https://app.example.com/mcp",
-  scopes: { "xixo:catalog:read" => "Search your catalog" }
-)
-
-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 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`.
-Its `scope_descriptions` extension gives masks the sentences its consent screen shows for each
-scope.
-
-A Rack middleware does the same below the framework, proof included:
-
-```ruby
-use Masks::Client::Rack, resource: resource, scope: "xixo:catalog:read"
-```
-
-### Introspection
-
-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?("xixo:catalog:read")
-```
-
-`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/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
-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, 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:
-
-```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)
-```
+Keep `started[:state]`, `started[:nonce]`, and `started[:verifier]` in the session, and send the
+browser to `started[:url]`. When it comes back, check `state` and `identity["nonce"]` against the
+values you kept.
 
 ## Documentation
 
-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.
+- [Rails apps](https://masks.pages.dev/reference/ruby/) covers the handshake, privileges,
+  organizations, accepting tokens, and running several processes.
+- [Masks::Client](https://masks.pages.dev/reference/ruby/client/) and
+  [Masks::Rails](https://masks.pages.dev/reference/ruby/rails/) list every class and setting.
 
 ## License
 

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

@@ -29,7 +29,7 @@ module Masks
       end
 
       def destroy
-        return redirect_to(masks_config.after_sign_out) unless masks_signed_in?
+        return redirect_to(masks_after_sign_out_path) unless masks_signed_in?
         return redirect_to(masks_handshake_path) unless masks_config.can_forget?
 
         forget_upstream
@@ -67,7 +67,7 @@ module Masks
           return unless masks_config.configured?(request)
           return if masks_signed_in?
 
-          redirect_to masks_config.after_sign_out
+          redirect_to masks_after_sign_out_path
         end
 
         def require_unconfigured_or_manager

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

@@ -7,25 +7,28 @@ module Masks
         return refuse("invalid_request", "logout_token is required") if params[:logout_token].blank?
 
         logout = masks_session.logout_token(params[:logout_token])
+        issuer = masks_config.issuer_for(request).to_s
 
-        heard = masks_config.logged_out!(request, logout)
+        return refuse("invalid_request", "that logout token was already used") unless masks_cache.first_logout?(issuer, logout)
+
+        masks_cache.depart!(issuer, logout)
+        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
+        head :ok
+      rescue Masks::Client::InvalidToken, Masks::Rails::Configuration::Unconfigured => e
         refuse("invalid_request", e.message)
+      rescue Masks::Client::Unreachable, Masks::Rails::Cache::Unavailable => e
+        refuse("temporarily_unavailable", e.message, status: :service_unavailable)
       end
 
       private
 
-        def refuse(code, description)
+        def refuse(code, description, status: :bad_request)
           response.headers["Cache-Control"] = "no-store"
 
-          render json: { "error" => code, "error_description" => description },
-                 status: :bad_request
+          render json: { "error" => code, "error_description" => description }, status: status
         end
     end
   end

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

@@ -3,6 +3,9 @@ module Masks
     class SessionsController < BaseController
       RESTARTED = "masks_restarted_at".freeze
       RESTART_WITHIN = 60
+      SAME_ORIGIN = %w[same-origin none].freeze
+
+      before_action :refuse_cross_site, only: :destroy
 
       def show
         if masks_configured? && (masks_signed_in? || (masks_tokens && masks_refresh!))
@@ -10,7 +13,7 @@ module Masks
 
           render json: masked.to_h
         else
-          masks_forget
+          masks_forget unless masks_configured?
           masks_refuse_json
         end
       end
@@ -40,7 +43,8 @@ module Masks
       def callback
         pending = masks_requests.claim(params[:state])
 
-        return refuse(params[:error], params[:error_description], pending) if params[:error].present?
+        return refuse(params[:error], params[:error_description], pending) if params[:error].present? && pending
+        return unstarted if params[:error].present?
         return stale if pending.nil?
 
         tokens = masks_session.complete(
@@ -73,24 +77,52 @@ module Masks
 
       def destroy
         everywhere = masks_config.sign_out_of_issuer || params[:everywhere].present?
-        upstream = everywhere ? masks_logout_url : nil
 
         revoke_refresh_token
         masks_forget
         reset_session
 
+        upstream = everywhere ? masks_sign_out_upstream : nil
+
         if masks_wants_json?
           render json: { "signed_in" => false, "logout_url" => upstream }.compact
         else
-          redirect_to upstream || masks_config.after_sign_out, allow_other_host: upstream.present?
+          redirect_to upstream || masks_after_sign_out_path, allow_other_host: upstream.present?
         end
       end
 
+      def signed_out
+        return stale_sign_out if masks_farewells.claim(params[:state].to_s).nil?
+
+        redirect_to masks_after_sign_out_path
+      end
+
       private
 
+        def refuse_cross_site
+          return if same_origin?
+
+          answer("invalid_request", "that request came from another site", :forbidden, failed: "sign-out")
+        end
+
+        def same_origin?
+          site = request.headers["Sec-Fetch-Site"].to_s
+
+          return false unless site.empty? || SAME_ORIGIN.include?(site)
+
+          sent = request.headers["Origin"].to_s
+
+          sent.empty? || [ request.base_url, own_origin ].include?(sent)
+        end
+
+        def own_origin
+          URI.join(masks_config.redirect_uri_for(request), "/").to_s.chomp("/")
+        end
+
         def renew_session
           carried = session.to_hash.slice(REQUESTS, HANDSHAKES, Masks::Rails::Authentication::STEPPED_UP)
 
+          masks_forget
           reset_session
           carried.each { |key, value| session[key] = value }
         end
@@ -129,6 +161,16 @@ module Masks
           )
         end
 
+        def unstarted
+          answer("invalid_state", "masks refused a sign-in that this browser did not start, or one that expired",
+                 :bad_request)
+        end
+
+        def stale_sign_out
+          answer("invalid_state", "that sign-out is not one this browser started, or it expired", :bad_request,
+                 failed: "sign-out")
+        end
+
         def restart
           session[RESTARTED] = Time.now.to_i
           redirect_to start_path
@@ -144,11 +186,11 @@ module Masks
           answer(code, description, :bad_request)
         end
 
-        def answer(code, description, status)
+        def answer(code, description, status, failed: "sign-in")
           if masks_wants_json?
             render json: { "error" => code, "error_description" => description }, status: status
           else
-            render plain: "sign-in failed — #{code}: #{description}", status: status
+            render plain: "#{failed} failed — #{code}: #{description}", status: status
           end
         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
+  get "/logout/return", to: "sessions#signed_out", as: :logout_return
   post "/logout/backchannel", to: "logouts#create", as: :backchannel_logout
 
   get "/handshake", to: "handshakes#show", as: :handshake