masks 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4455d2e731a770253802292bce1dd21a9b97c05489e65ba4a1f310c24873b79
-  data.tar.gz: df05e39f40a1f08fbb77897549c584653bf17676c3e6b13b64220e1751360e64
+  metadata.gz: 3ec26aa454cf249dd26ce7e15444b43890e4e75954968c76cba3297b63f9819e
+  data.tar.gz: 19609ef3a180ab7d6c675cac13cef843adb3ffc742d83b7fd64d7120bbcc93b5
 SHA512:
-  metadata.gz: 39e55aecad7e80a3cef669b9bcbe16f6f942c326bf98a9f9da954663365740d9e31a814a3da644ef68bd0090f040f853ff4b3bdda34f2f8fe6dd4b749190d138
-  data.tar.gz: 4cca8c0d431151c0a0865969dcc38767388ec4f93c1ab5e2b824e7dd875f8a38135969d7b8ed5a1966eb9b0f51b3fb60e8cff887c67d180561b3474e47653d84
+  metadata.gz: 4a02a532dc018b73c27b350da38335b5ec27c5665d8b498564fd11b220e386919df8ecc9a24b80fb62f21d193c7a66166e99d2dc41c86fef3cb515f5aacc2b0d
+  data.tar.gz: fbbb524a91dda55fc6ccf631d1ef8b270b9ff9835b894855dcd0dd07a054fcfb380c6fdea75930b93950909ba1e3618940215418c9fca7f0a5f32e30b33c96b4

data/CHANGELOG.md

@@ -1,5 +1,70 @@
 # Changelog
 
+## [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)
+
+
+### ⚠ BREAKING CHANGES
+
+* **client:** Masks::Client::Introspection#username is now #nickname.
+
+### Features
+
+* **client:** an app can act on a logout the issuer tells it about ([4d0b7f7](https://github.com/masksrb/masks/commit/4d0b7f77a74b0e416dda3e90413ad989a909f344))
+* **client:** an app that delegates asks its handshake for masks:delegate: and the token exchange ([912e856](https://github.com/masksrb/masks/commit/912e856b00a9f27d59af861cdb35da518fa862bc))
+* **client:** an app that delegates registers where connecting a person's account comes back to ([738fba6](https://github.com/masksrb/masks/commit/738fba67e544f7c8a9a15cd55befbd66696b707b))
+* **client:** an unconnected app walks straight into the handshake ([040388e](https://github.com/masksrb/masks/commit/040388e188653f67ef7a59bc0aa9aef02ec351b2))
+* **server:** an application is let use somebody's account elsewhere through a delegation ([4b7048c](https://github.com/masksrb/masks/commit/4b7048cb8ac4e174b9359a070b7a2d942a1c410d))
+
+
+### Fixes
+
+* **client:** back-channel logout says 501 when the app does nothing about it ([60e1125](https://github.com/masksrb/masks/commit/60e1125c02adec7c822c6d3757210e825bb66cfc))
+
+
+### Documentation
+
+* hold the copyright as the masks authors ([cffdeb5](https://github.com/masksrb/masks/commit/cffdeb59f14eb02f6a9513d5f7cda21ebaee2171))
+* READMEs that match the code, and a server one that is not the scaffold ([e0148e1](https://github.com/masksrb/masks/commit/e0148e14e0092731bcd095bc0fc22a1589c3acc0))
+* references are generated from the code that defines them ([ba74550](https://github.com/masksrb/masks/commit/ba745501e651b797948e5abd5640a1825616100c))
+* the gem reference survives rdoc 8, and lists what a Concern adds ([36df12e](https://github.com/masksrb/masks/commit/36df12e72cc52f5db650d16778ecc501bf9db14a))
+* the rose window is the site's logo, favicon and hero, and heads every README ([72176e4](https://github.com/masksrb/masks/commit/72176e49c81bc0a5d6730f3b9e5eaa693db8a659))
+
+
+### Refactoring
+
+* **client:** an introspection answers a nickname, not a username ([f23dff5](https://github.com/masksrb/masks/commit/f23dff537320982d42a8e4823bea784a3d80ec33))
+* comments are gone; the code says what it does ([0fc8e6a](https://github.com/masksrb/masks/commit/0fc8e6a4692e3f09831514b6d167c3e23d7db419))
+* every suite is named for what it proves, under one test directory ([315b371](https://github.com/masksrb/masks/commit/315b371e64baa4441014669744a61c88341d27c7))
+* rename the example tenant from jons to demo ([aef32a6](https://github.com/masksrb/masks/commit/aef32a670b4b3c696089c07bf15103e1d981eb00))
+* **server:** delegation shares what sign-in and linking already had, and asks the database less ([44b8c4d](https://github.com/masksrb/masks/commit/44b8c4d303dfcc6de60f98d7824c544bd67e347c))
+* take the owner's domain out of the boundary check ([df580ee](https://github.com/masksrb/masks/commit/df580ee1fb5820d30a57a88f3aa9825c97682725))
+
 ## [0.6.0](https://github.com/masksrb/masks/compare/gem-v0.5.0...gem/v0.6.0) (2026-09-05)
 
 

data/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 geiger.to
+Copyright (c) 2026 the masks authors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,3 +1,5 @@
+<p align="center"><img src="https://raw.githubusercontent.com/masksrb/masks/main/engine/public/masks-public/icon.svg" width="120" alt="The masks rose window"></p>
+
 # masks
 
 Sign a Ruby or Rails app in against a [masks](https://github.com/masksrb/masks) issuer.
@@ -7,9 +9,9 @@ gem "masks"
 ```
 
 Three parts, in one gem. **Consumers spend tokens. Resource servers accept them.** Most
-client libraries only build the first, so everything above the second gets written by
-hand in each resource server — its scope check, its `WWW-Authenticate` header, its
-metadata document. Both halves are here, and a Rails engine that mounts them.
+client libraries build only the first, leaving each resource server to write its own
+scope check, its `WWW-Authenticate` header and its metadata document. Both halves are
+here, with a Rails engine that mounts them.
 
 The engine loads only when Rails does. A Sinatra, Hanami or plain-Rack app requiring
 this gem pulls in `jwt` and nothing else.
@@ -29,12 +31,16 @@ the file credentials land in. Set `MASKS_ISSUER`, start the app, and open
 
 ### The handshake
 
-A first-party app must not self-register anonymously — that is how a stranger's
-connector also arrives. So an unconnected app is offered one button, the browser goes to
-its own issuer's approval screen, and the one-time token that comes back is redeemed
+A first-party app must not self-register anonymously, since that is also how a
+stranger's connector arrives. An unconnected app sends the browser straight on to its
+own issuer's approval screen, and the one-time token that comes back is redeemed
 server-side. **The secret never travels through the browser and nobody types it
 anywhere.**
 
+The only thing `/auth/handshake` stops a browser to say is that the app is configured
+too little to shake hands at all, or that the issuer refused. A connected app asks
+before it rotates, since reconnecting takes it offline for a moment.
+
 The engine writes what comes back to `config/masks.json`, mode 600. An app that wants
 somewhere else says so:
 
@@ -48,7 +54,7 @@ Those two lambdas are the whole integration for a multi-tenant app.
 ### Signing in
 
 ```ruby
-class ThingsController < ApplicationController
+class UrisController < ApplicationController
   include Masks::Rails::Authentication
 
   before_action :authenticate_masks!
@@ -60,7 +66,7 @@ end
 ```
 
 `masks_identity`, `masks_tenant` and `masks_scopes` are what a signed-in request carries.
-Tokens live in the encrypted Rails session and never reach JavaScript — this is the
+Tokens live in the encrypted Rails session and never reach JavaScript. This is the
 backend-for-frontend pattern, and it is the default because an SPA holding a token is an
 SPA where XSS lifts one.
 
@@ -70,7 +76,7 @@ controller if that is what you want; otherwise include it where you mean it.
 ### An SPA in front of it
 
 `GET /auth/session` answers identity, tenant and scopes as JSON, or `401` with somewhere
-to send the browser. [`@masks/client`](../web) speaks it:
+to send the browser. [`@masks/client`](https://masks.pages.dev/reference/browser/) speaks it:
 
 ```js
 import { createSession } from "@masks/client"
@@ -79,10 +85,9 @@ const session = createSession()
 const status = await session.status()
 ```
 
-`status()` answers one of three things, and the third is why it exists: `signed_in`,
-`signed_out` with where to sign in, and `handshake_required` with where to go instead —
-because an app nobody has connected must not offer a sign-in button that leads to an
-error page at the issuer.
+`status()` answers one of three states: `signed_in`, `signed_out` with where to sign in,
+and `handshake_required` with where to go instead. The third exists because an app nobody
+has connected must not offer a sign-in button that leads to an error page at the issuer.
 
 ### Accepting tokens
 
@@ -92,14 +97,62 @@ An app that is also a resource server:
 class ApiController < ApplicationController
   include Masks::Rails::ProtectedResource
 
-  before_action { masks_protect!(scope: "things:read") }
+  masks_protect! scope: "uris:catalog:read"
 end
 ```
 
+`masks_protect!` is a class method that installs the `before_action` itself, and passes `:only` and
+`:except` through.
+
 `masks_claims` is the verified token. A refusal carries the RFC 6750 challenge with
 `resource_metadata`, so a client handed nothing but a URL can find its way to the issuer
 and back.
 
+### 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.
+
+```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; the app just learns nothing about the role.
+
 ### Avatars
 
 Every actor has three faces at once — an uploaded `photo`, an `identicon`, and two-letter
@@ -138,6 +191,7 @@ a subdomain-per-tenant host needs.
 | `resource` | this app's own identifier, when it also accepts tokens |
 | `resource_scopes` | what it accepts, published in its RFC 9728 metadata |
 | `scope` | what to ask the issuer for; defaults to `openid profile email` |
+| `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` |
 | `after_sign_in` / `after_sign_out` | paths on this host |
@@ -155,7 +209,7 @@ holds no protocol of its own.
 
 ```ruby
 session = Masks::Client::Session.new(
-  issuer: "https://jons.auth.example.com",
+  issuer: "https://demo.auth.example.com",
   client_id: id, client_secret: secret,
   redirect_uri: "https://app.example.com/auth/callback"
 )
@@ -169,8 +223,7 @@ identity = session.identity(tokens)
 ```
 
 `start` sends a nonce only when `openid` was asked for, so holding one means an id token
-is owed — which is what lets the check on the way back be exact rather than vacuously
-true.
+is owed, and the check on the way back is exact.
 
 Also: `refresh`, `exchange`, `revoke`, `introspect`, `userinfo`, and `end_session_url`.
 
@@ -181,12 +234,11 @@ constructing one per request.
 
 ### The handshake
 
-The flow that connects a first-party app, rather than two helpers and sixty lines of
-state in every consumer:
+The flow that connects a first-party app:
 
 ```ruby
 handshake = Masks::Client::Handshake.new(
-  issuer, name: "things", resource: "https://app.example.com/mcp",
+  issuer, name: "uris", resource: "https://app.example.com/mcp",
   redirect_uris: [ "https://app.example.com/auth/callback" ],
   return_to: "https://app.example.com/"
 )
@@ -202,12 +254,12 @@ that is not the issuer it asked — each **before** anything is redeemed.
 
 ```ruby
 resource = Masks::Client::Resource.new(
-  issuer: "https://jons.auth.example.com",
+  issuer: "https://demo.auth.example.com",
   url: "https://app.example.com/mcp",
-  scopes: { "things:read" => "Search your catalog" }
+  scopes: { "uris:catalog:read" => "Search your catalog" }
 )
 
-claims = resource.authenticate(request.authorization, scope: "things:read")
+claims = resource.authenticate(request.authorization, scope: "uris:catalog:read")
 claims.subject
 claims.tenant.subdomain
 ```
@@ -221,35 +273,87 @@ response.headers["WWW-Authenticate"] = resource.challenge(error)
 
 `resource.metadata` is the RFC 9728 document to serve at
 `/.well-known/oauth-protected-resource`. The `scope_descriptions` extension in it is how
-an auth server renders your scopes as sentences on its consent screen — it has no other
-way to know what `things:read` means.
+an auth server renders your scopes as sentences on its consent screen; it has no other
+way to know what `uris:catalog:read` means.
 
 There is a Rack middleware for consumers that want the challenge below the framework:
 
 ```ruby
-use Masks::Client::Rack, resource: resource, scope: "things:read"
+use Masks::Client::Rack, resource: resource, scope: "uris:catalog:read"
 ```
 
 ### Introspection
 
 A resource server doing JWT-only validation cannot see a revocation until the token
-expires. Asking is the honest answer:
+expires. Ask the issuer instead:
 
 ```ruby
 found = session.introspect(token)
-found.active? && found.permits?("things:read")
+found.active? && found.permits?("uris:catalog:read")
 ```
 
 `Introspection` is a `Claims` whose `permit!` raises when the issuer says the token is
-not active, so switching from local verification to asking does not mean remembering to
-check a boolean.
+not active, so moving from local verification to introspection needs no extra boolean
+check.
+
+### Somebody else's account
+
+An app that acts as somebody at Google, Microsoft or an MCP server while they are away asks masks for
+a [delegation](https://masks.pages.dev/concepts/delegation/). masks keeps and refreshes the
+provider's tokens; the app keeps one secret per connection and trades it for a live access token when
+the last one runs out.
+
+```ruby
+delegations = Masks::Client.delegations(
+  ENV["MASKS_ISSUER"], client_id: id, client_secret: secret, redirect_uri: "https://app.test/connect/callback"
+)
+
+started = delegations.start(provider: "google")
+session[:connecting] = started
+redirect_to started["url"]
+
+held = delegations.finish(params: params, started: session.delete(:connecting))
+held.connection
+held.secret
+
+upstream = delegations.token(held.secret, connection: held.connection)
+upstream.access_token
+upstream.expires_at
+upstream.secret
+```
+
+A Rails app sets `config.delegates = true`, so its handshake asks for `masks:delegate:` and the token
+exchange with it.
+
+`upstream.secret` replaces the one you passed in, every time. `Delegations::Refused` means somebody
+has to connect again; `Delegations::Unavailable` is worth retrying. Both carry `secret` when masks had
+already rotated it, so keep it. Spend a secret from one place at a time: spending one twice revokes
+it.
+
+Tests use the fake, which needs no issuer:
+
+```ruby
+require "masks/client/delegations/fake"
+
+fake = Masks::Client::Delegations::Fake.new
+started = fake.start(provider: "notion")
+held = fake.finish(params: fake.approve(started), started: started)
+
+fake.token(held.secret, connection: held.connection)
+fake.revoke(held.connection)
+fake.unavailable(held.connection)
+```
 
 ## Which issuers this speaks to
 
 masks publishes `masks_protocol_version` in its discovery document, and this gem needs at
 least version 1 — the one that serves `handshake_endpoint` and the approval flow behind
-it. An older issuer is refused with a sentence saying so, rather than at the first screen
-anybody touches.
+it. An older issuer is refused at configuration time, with a sentence saying so.
+
+## Documentation
+
+This README is the reference for the gem. [masks.pages.dev](https://masks.pages.dev) carries what is
+generated from the server's own code — the `/manage` GraphQL schema, and the design system.
 
 ## License
 

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

@@ -4,17 +4,13 @@ module Masks
       before_action :require_unconfigured_or_signed_in
 
       def show
-        @connected = masks_config.configured?(request)
-        @can_disconnect = @connected && masks_config.can_forget?
+        return begin! unless masks_config.configured?(request)
+
+        @can_disconnect = masks_config.can_forget?
       end
 
       def create
-        pending = masks_handshakes.open
-        started = masks_config.handshake_for(request).start(state: pending.id)
-
-        redirect_to started[:url], allow_other_host: true
-      rescue Masks::Client::Error => e
-        refuse(e)
+        begin!
       end
 
       def callback
@@ -31,10 +27,6 @@ module Masks
         refuse(e)
       end
 
-      # Rotating is what masks does with a second run — the client is keyed on
-      # the resource identifier, so approving again replaces the credentials
-      # rather than leaving a tenant with two and no way to tell which one the
-      # browser holds. Disconnecting is the other half, and it is RFC 7592.
       def destroy
         return redirect_to(masks_config.after_sign_out) unless masks_signed_in?
         return redirect_to(masks_handshake_path) unless masks_config.can_forget?
@@ -51,6 +43,15 @@ module Masks
 
       private
 
+        def begin!
+          pending = masks_handshakes.open
+          started = masks_config.handshake_for(request).start(state: pending.id)
+
+          redirect_to started[:url], allow_other_host: true
+        rescue Masks::Client::Error => e
+          refuse(e)
+        end
+
         def forget_upstream
           masks_registration&.delete
         rescue Masks::Client::Unregistered

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

@@ -0,0 +1,32 @@
+module Masks
+  module Rails
+    class LogoutsController < BaseController
+      skip_forgery_protection
+
+      def create
+        return refuse("invalid_request", "logout_token is required") if params[:logout_token].blank?
+
+        logout = masks_session.logout_token(params[:logout_token])
+
+        heard = masks_config.logged_out!(request, logout)
+
+        response.headers["Cache-Control"] = "no-store"
+
+        head(heard ? :ok : :not_implemented)
+      rescue Masks::Client::InvalidToken => e
+        refuse("invalid_request", e.message)
+      rescue Masks::Rails::Configuration::Unconfigured => e
+        refuse("invalid_request", e.message)
+      end
+
+      private
+
+        def refuse(code, description)
+          response.headers["Cache-Control"] = "no-store"
+
+          render json: { "error" => code, "error_description" => description },
+                 status: :bad_request
+        end
+    end
+  end
+end

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

@@ -21,7 +21,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(

data/app/views/masks/rails/handshakes/show.html.erb

@@ -1,40 +1,24 @@
-<% if @connected %>
-  <% content_for :title, "Reconnect this app" %>
+<% content_for :title, "Reconnect this app" %>
 
-  <h1>This app is connected</h1>
+<h1>This app is connected</h1>
 
-  <p class="muted">
-    Reconnecting replaces the credentials it holds now with a fresh pair. It is
-    how you rotate them, and it is the only way to move this app to a different
-    account. Nothing is typed in and no secret travels through your browser.
-  </p>
+<p class="muted">
+  Reconnecting replaces the credentials it holds now with a fresh pair. It is
+  how you rotate them, and it is the only way to move this app to a different
+  account. Nothing is typed in and no secret travels through your browser.
+</p>
 
-  <p class="muted">
-    It will stop working between the approval and the moment it picks the new
-    credentials up.
-  </p>
+<p class="muted">
+  It will stop working between the approval and the moment it picks the new
+  credentials up.
+</p>
 
-  <%= form_with url: handshake_path, method: :post do %>
-    <button type="submit">Reconnect it</button>
-  <% end %>
-
-  <% if @can_disconnect %>
-    <%= form_with url: handshake_path, method: :delete do %>
-      <button type="submit">Disconnect it</button>
-    <% end %>
-  <% end %>
-<% else %>
-  <% content_for :title, "Connect this app" %>
-
-  <h1>This app has not been connected yet</h1>
-
-  <p class="muted">
-    Nobody can sign in here until it holds credentials from the server that signs
-    people in. Getting them takes one approval, from whoever owns this tenant —
-    nothing is typed in, and no secret travels through your browser.
-  </p>
+<%= form_with url: handshake_path, method: :post do %>
+  <button type="submit">Reconnect it</button>
+<% end %>
 
-  <%= form_with url: handshake_path, method: :post do %>
-    <button type="submit">Connect it</button>
+<% if @can_disconnect %>
+  <%= form_with url: handshake_path, method: :delete do %>
+    <button type="submit">Disconnect it</button>
   <% end %>
 <% end %>

data/config/routes.rb

@@ -4,6 +4,7 @@ Masks::Rails::Engine.routes.draw do
   get "/avatar", to: "avatars#show", as: :avatar
   get "/callback", to: "sessions#callback", as: :callback
   match "/logout", to: "sessions#destroy", via: %i[get post delete], as: :logout
+  post "/logout/backchannel", to: "logouts#create", as: :backchannel_logout
 
   get "/handshake", to: "handshakes#show", as: :handshake
   post "/handshake", to: "handshakes#create"

data/lib/masks/client/claims.rb

@@ -60,7 +60,51 @@ module Masks
         end
       end
 
+      class Organization
+        OWNER = "owner".freeze
+
+        attr_reader :to_h
+
+        def initialize(hash)
+          @to_h = hash.is_a?(Hash) ? hash.transform_keys(&:to_s) : {}
+        end
+
+        def id
+          to_h["id"]
+        end
+
+        def key
+          to_h["key"]
+        end
+
+        def name
+          to_h["name"]
+        end
+
+        def role
+          to_h["role"]
+        end
+
+        def role?(*roles)
+          roles.flatten.map(&:to_s).include?(role)
+        end
+
+        def owner?
+          role?(OWNER)
+        end
+
+        def present?
+          !id.nil? && !key.nil? && !role.nil?
+        end
+
+        def ==(other)
+          other.is_a?(Organization) ? to_h == other.to_h : false
+        end
+      end
+
       AVATARS = "masks:avatars".freeze
+      ORGANIZATION = "org".freeze
+      ORGANIZATIONS = "orgs".freeze
 
       attr_reader :to_h
 
@@ -104,6 +148,31 @@ module Masks
         @avatars ||= Avatars.new(self[AVATARS])
       end
 
+      def organization
+        @organization ||= Organization.new(self[ORGANIZATION])
+      end
+
+      def organizations
+        @organizations ||= Array(self[ORGANIZATIONS]).map { |held| Organization.new(held) }.select(&:present?).freeze
+      end
+
+      def member!(*roles, organization: nil)
+        held = self.organization
+
+        unless held.present?
+          raise Forbidden.new("insufficient_organization", "this token names no organization",
+                              scope: Session::ORGANIZATION)
+        end
+
+        if organization && held.key != organization.to_s && held.id != organization.to_s
+          raise Forbidden.new("insufficient_organization", "this token was issued for #{held.key}, not #{organization}")
+        end
+
+        return held if roles.flatten.empty? || held.role?(*roles)
+
+        raise Forbidden.new("insufficient_role", "#{held.role} in #{held.key} is not #{roles.flatten.join(' or ')}")
+      end
+
       def picture
         self["picture"] || avatars.photo || avatars.identicon
       end