masks 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ae9f82c2ea49310531a78988041b88fc46c35dfeb8d4e1beb1ad293c0845b0c
-  data.tar.gz: d17941873e5162c547e93f1ff18f38eb6ab7594846ea44d1de85d8f3410957ec
+  metadata.gz: d4455d2e731a770253802292bce1dd21a9b97c05489e65ba4a1f310c24873b79
+  data.tar.gz: df05e39f40a1f08fbb77897549c584653bf17676c3e6b13b64220e1751360e64
 SHA512:
-  metadata.gz: 5f639e855aa5d28fc184c816b360fb97e7df03da827a6537451bc3e7bf7e4a3759e7d5c5f162c0b5e4c8e45939c7cb6c6bfde3ef08749e26299ddea137f4be84
-  data.tar.gz: c61938382dea4c955e7c207e9d889b5db3d23c843b10e7783c18b81886f3f5c38a7f55d30d47d3f15689164356ba64816ac3e3321c65569dcb0b01dba66ef57d
+  metadata.gz: 39e55aecad7e80a3cef669b9bcbe16f6f942c326bf98a9f9da954663365740d9e31a814a3da644ef68bd0090f040f853ff4b3bdda34f2f8fe6dd4b749190d138
+  data.tar.gz: 4cca8c0d431151c0a0865969dcc38767388ec4f93c1ab5e2b824e7dd875f8a38135969d7b8ed5a1966eb9b0f51b3fb60e8cff887c67d180561b3474e47653d84

data/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## [0.6.0](https://github.com/masksrb/masks/compare/gem-v0.5.0...gem/v0.6.0) (2026-09-05)
+
+
+### Features
+
+* **server:** a namespace is a grant, so an app can grow its own scopes ([4e816e4](https://github.com/masksrb/masks/commit/4e816e4456de9cc05601b8eaa03773788e3178bb))
+* **server:** people, avatars, and one page instead of three ([d50c444](https://github.com/masksrb/masks/commit/d50c4440812fc1c3a92e926ff6d533b9a69dae2a))
+
+
+### Fixes
+
+* **client:** an app whose issuer forgot it asks to be reconnected ([6956972](https://github.com/masksrb/masks/commit/695697233ca1ce35fa8b29ea74e58dd0d762b0a5))
+
+## 0.5.0 — unreleased
+
+First release carrying the consumer half in full. 0.4.0 predates the split described in
+`plans/019` and should not be used.
+
+- Discovery, PKCE authorization, token exchange, and token verification against a masks issuer.
+- Rack middleware for a resource server.
+- A Rails engine, mounted by the consuming app, covering the consumer half of the code flow.
+- `rails generate masks:install`.
+- `config.store` falls back to a default credential store instead of raising.
+
+## 0.4.0
+
+Withdrawn. An earlier design, published 2024-04-11 and marked "DO NOT USE".

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 geiger.to
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,50 +1,256 @@
 # masks
 
-masks is a general purpose access control framework for ruby/rails.
+Sign a Ruby or Rails app in against a [masks](https://github.com/masksrb/masks) issuer.
 
-## Getting started
+```ruby
+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.
+
+The engine loads only when Rails does. A Sinatra, Hanami or plain-Rack app requiring
+this gem pulls in `jwt` and nothing else.
 
-To use it, add `masks` to your Gemfile or run:
+## Rails
+
+One command to install, and the app is connected by somebody approving it — no client
+id to copy, no secret to paste anywhere.
 
 ```
-bundle add masks
+bin/rails generate masks:install
 ```
 
-Then run the install generator:
+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`.
+
+### 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
+server-side. **The secret never travels through the browser and nobody types it
+anywhere.**
+
+The engine writes what comes back to `config/masks.json`, mode 600. An app that wants
+somewhere else says so:
+
+```ruby
+config.credentials = ->(request) { Tenant.for(request).masks_credentials }
+config.store = ->(request, registration) { Tenant.for(request).connect!(registration) }
 ```
-rails generate masks:install
+
+Those two lambdas are the whole integration for a multi-tenant app.
+
+### Signing in
+
+```ruby
+class ThingsController < ApplicationController
+  include Masks::Rails::Authentication
+
+  before_action :authenticate_masks!
+
+  def index
+    @who = masks_identity
+  end
+end
 ```
 
-A typical install creates a `masks.json`, an initializer, and migrations. After
-running the generator your app will be able to use masks' signup, login, and account
-management features. Every route in your app will be protected by login by default.
+`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.
+
+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.
 
-## Documentation
+### An SPA in front of it
 
-Full documentation is available at [masks.geiger.to](https://masks.geiger.to).
+`GET /auth/session` answers identity, tenant and scopes as JSON, or `401` with somewhere
+to send the browser. [`@masks/client`](../web) speaks it:
 
-## How it works
+```js
+import { createSession } from "@masks/client"
 
-At the heart of masks are a few key concepts:
+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.
 
-- **Masks** are rules that define access to resources in your application
-- **Actors** access resources via sessions (if allowed by the mask)
-- **Sessions** keep track of attempts to access resources
-- **Credentials** identify and check actors' access using session data
+### Accepting tokens
 
-masks implements most of the glue code required to build actors, open sessions,
-and check credentials, leaving your application to defining the _masks_ required
-for it to function. typically all you need is a `masks.json` file, but you can
-also build custom credentials, checks, models, and more...
+An app that is also a resource server:
 
-#### an example `masks.json`
+```ruby
+class ApiController < ApplicationController
+  include Masks::Rails::ProtectedResource
 
-```json
-{
-  "name": "example",
-  "url": "http://example.com",
-  "logo": "...",
-  "extend": "masks"
-}
+  before_action { masks_protect!(scope: "things:read") }
+end
 ```
+
+`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.
+
+### 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.
+
+```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:
+
+```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.
+
+### 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.
+
+### 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, 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` |
+| `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 |
+| `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 |
+
+## Any Ruby app
+
+Everything above is `Masks::Client` underneath, and it is usable directly — the engine
+holds no protocol of its own.
+
+### The consumer half
+
+```ruby
+session = Masks::Client::Session.new(
+  issuer: "https://jons.auth.example.com",
+  client_id: id, client_secret: secret,
+  redirect_uri: "https://app.example.com/auth/callback"
+)
+
+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 — which is what lets the check on the way back be exact rather than vacuously
+true.
+
+Also: `refresh`, `exchange`, `revoke`, `introspect`, `userinfo`, and `end_session_url`.
+
+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.
+
+### The handshake
+
+The flow that connects a first-party app, rather than two helpers and sixty lines of
+state in every consumer:
+
+```ruby
+handshake = Masks::Client::Handshake.new(
+  issuer, name: "things", 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
+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.
+
+### The resource-server half
+
+```ruby
+resource = Masks::Client::Resource.new(
+  issuer: "https://jons.auth.example.com",
+  url: "https://app.example.com/mcp",
+  scopes: { "things:read" => "Search your catalog" }
+)
+
+claims = resource.authenticate(request.authorization, scope: "things:read")
+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:
+
+```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 `things: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"
+```
+
+### Introspection
+
+A resource server doing JWT-only validation cannot see a revocation until the token
+expires. Asking is the honest answer:
+
+```ruby
+found = session.introspect(token)
+found.active? && found.permits?("things: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.
+
+## 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.
+
+## License
+
+MIT.

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

@@ -0,0 +1,51 @@
+module Masks
+  module Rails
+    class AvatarsController < BaseController
+      SIZES = [ 32, 64, 128, 256, 512 ].freeze
+
+      def show
+        return head :not_found unless masks_signed_in?
+
+        url = photo_url
+
+        return head :not_found if url.nil?
+
+        deliver(
+          Masks::Client::HTTP.fetch(
+            url, "Authorization" => masks_tokens.authorization, "Accept" => "image/*"
+          )
+        )
+      rescue Masks::Client::Error
+        head :bad_gateway
+      end
+
+      private
+
+        def photo_url
+          held = masks_claims.avatars.photo
+
+          return nil if held.nil?
+          return nil unless held.start_with?("#{masks_config.issuer_for(request)}/")
+
+          asked = params[:size].presence
+
+          return held if asked.nil?
+
+          "#{held}?size=#{SIZES.find { |allowed| allowed >= asked.to_i } || SIZES.last}"
+        end
+
+        def deliver(answer)
+          case answer
+          when Net::HTTPRedirection
+            redirect_to answer["Location"], allow_other_host: true
+          when Net::HTTPSuccess
+            expires_in 5.minutes, public: false
+
+            send_data answer.body, type: answer["Content-Type"], disposition: "inline"
+          else
+            head :not_found
+          end
+        end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+module Masks
+  module Rails
+    def self.parent_controller
+      config.parent_controller.to_s.constantize
+    end
+
+    class BaseController < parent_controller
+      include Masks::Rails::Authentication
+
+      layout "masks/rails/plain"
+    end
+  end
+end

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

@@ -0,0 +1,86 @@
+module Masks
+  module Rails
+    class HandshakesController < BaseController
+      before_action :require_unconfigured_or_signed_in
+
+      def show
+        @connected = masks_config.configured?(request)
+        @can_disconnect = @connected && 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)
+      end
+
+      def callback
+        pending = masks_handshakes.claim(params[:state])
+
+        return stale if pending.nil?
+
+        registration = masks_config.handshake_for(request).complete(returned, state: pending.id)
+
+        masks_config.store!(request, registration)
+
+        redirect_to Masks::Rails::Engine.routes.url_helpers.start_path
+      rescue Masks::Client::Error => e
+        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?
+
+        forget_upstream
+
+        masks_config.forget!(request)
+        masks_forget
+
+        redirect_to masks_handshake_path
+      rescue Masks::Client::Error => e
+        refuse(e)
+      end
+
+      private
+
+        def forget_upstream
+          masks_registration&.delete
+        rescue Masks::Client::Unregistered
+          false
+        end
+
+        def returned
+          params.permit(:initial_access_token, :iss, :state, :error, :error_description).to_h
+        end
+
+        def require_unconfigured_or_signed_in
+          return unless masks_config.configured?(request)
+          return if masks_signed_in?
+
+          redirect_to masks_config.after_sign_out
+        end
+
+        def stale
+          @code = "invalid_state"
+          @description = "that connection request is not one this browser started, or it expired"
+
+          render :refused, status: :bad_request
+        end
+
+        def refuse(error)
+          @code = error.try(:code).presence || error.class.name.demodulize.underscore
+          @description = error.try(:description).presence || error.message
+
+          render :refused, status: :bad_request
+        end
+    end
+  end
+end

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

@@ -0,0 +1,118 @@
+module Masks
+  module Rails
+    class SessionsController < BaseController
+      def show
+        if masks_configured? && (masks_signed_in? || (masks_tokens && masks_refresh!))
+          response.headers["Cache-Control"] = "no-store"
+
+          render json: masks_account
+        else
+          masks_forget
+          masks_refuse_json
+        end
+      end
+
+      def start
+        return redirect_to(masks_handshake_path) unless masks_configured?
+        return redirect_to(masks_handshake_path) if masks_reconnect!
+
+        pending = masks_requests.open(
+          return_to: requested_return_to || session.delete(:masks_return_to)
+        )
+        started = masks_session.start(
+          state: pending.id,
+          resource: masks_config.resource_for(request)
+        )
+
+        masks_requests.amend(
+          pending.id, nonce: started[:nonce], verifier: started[:verifier]
+        )
+
+        redirect_to started[:url], allow_other_host: true
+      end
+
+      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?
+
+        tokens = masks_session.complete(
+          code: params[:code],
+          verifier: pending[:verifier],
+          resource: masks_config.resource_for(request)
+        )
+
+        identity = begin
+          masks_identity_from(tokens)
+        rescue Masks::Client::InvalidToken
+          :unverified
+        end
+
+        unless nonce_matches?(identity, pending[:nonce])
+          return refuse("invalid_nonce", "the id token was issued for another request", pending)
+        end
+
+        masks_store(tokens, identity: identity)
+
+        redirect_to pending[:return_to] || masks_config.after_sign_in
+      rescue Masks::Client::Unregistered => e
+        return redirect_to(masks_handshake_path) if masks_disconnect!
+
+        refuse(e.code, e.description, pending)
+      rescue Masks::Client::Error => e
+        refuse(e.class.name.demodulize.underscore, e.message, pending)
+      end
+
+      def destroy
+        everywhere = masks_config.sign_out_of_issuer || params[:everywhere].present?
+        upstream = everywhere ? masks_logout_url : nil
+
+        masks_forget
+
+        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?
+        end
+      end
+
+      private
+
+        def requested_return_to
+          masks_local_path(params[:return_to])
+        end
+
+        def nonce_matches?(identity, sent)
+          return false if identity == :unverified
+          return true if sent.blank?
+          return false unless identity.is_a?(Hash)
+
+          held = identity["nonce"].to_s
+          held.present? && ActiveSupport::SecurityUtils.secure_compare(held, sent)
+        end
+
+        def stale
+          answer(
+            "invalid_state",
+            "that sign-in request is not one this browser started, or it expired",
+            :bad_request
+          )
+        end
+
+        def refuse(code, description, pending = nil)
+          masks_forget if pending
+
+          answer(code, description, :bad_request)
+        end
+
+        def answer(code, description, status)
+          if masks_wants_json?
+            render json: { "error" => code, "error_description" => description }, status: status
+          else
+            render plain: "sign-in failed — #{code}: #{description}", status: status
+          end
+        end
+    end
+  end
+end

data/app/views/layouts/masks/rails/plain.html.erb

@@ -0,0 +1,47 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title><%= yield :title %></title>
+    <%= csrf_meta_tags %>
+    <style>
+      :root { color-scheme: light dark; }
+      body {
+        margin: 0;
+        min-height: 100vh;
+        display: grid;
+        place-items: center;
+        padding: 2rem 1rem;
+        font: 15px/1.6 ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+        background: Canvas;
+        color: CanvasText;
+      }
+      main { width: 100%; max-width: 34rem; display: flex; flex-direction: column; gap: 1rem; }
+      h1 { margin: 0; font-size: 1.5rem; line-height: 1.25; }
+      p { margin: 0; }
+      .muted { opacity: 0.75; font-size: 0.9375rem; }
+      .box {
+        border: 1px solid color-mix(in srgb, CanvasText 20%, transparent);
+        border-radius: 0.5rem;
+        padding: 0.5rem 0.75rem;
+        font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+        font-size: 0.8125rem;
+        word-break: break-all;
+      }
+      button {
+        font: inherit;
+        font-weight: 600;
+        padding: 0.625rem 1rem;
+        border: 0;
+        border-radius: 0.5rem;
+        background: AccentColor;
+        color: AccentColorText;
+        cursor: pointer;
+      }
+    </style>
+  </head>
+  <body>
+    <main><%= yield %></main>
+  </body>
+</html>

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

@@ -0,0 +1,12 @@
+<% content_for :title, "This app could not be connected" %>
+
+<h1>This app could not be connected</h1>
+
+<p class="muted">
+  Nothing was connected and nothing was shared. The server that signs people in
+  refused, or answered something this app will not accept.
+</p>
+
+<p class="box"><%= @code %>: <%= @description %></p>
+
+<p class="muted"><a href="<%= handshake_path %>">Try again</a></p>