masks 0.3.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fbdad2d43a1f7948d3f3126e9e1d2126a38bcf2c3480db342b2fd09ece185869
-  data.tar.gz: 816478ae377ebc0e41c11eee01e1a7664adf86f7bdb7d58d532b80e414873425
+  metadata.gz: fab2f5044bc29a407688ac0c61ac703108849a24579a7aa2e30e18234d6e02f0
+  data.tar.gz: 64572497372118a8ac2677634c26349c53cf93e4850188ceecaa2e2610d18546
 SHA512:
-  metadata.gz: 7d9c773dc6aea440ea7fc36be2b4f2984fc8384def88750e602c50fb1319afeb5681299eef2f2ef26e06c4b4173d52e50c902c9fe748e1c3842f7a208c0fbca2
-  data.tar.gz: 1fca95503ff8721d83c4e6cd3b3480d9bc67c5ac64d9bfcd19747c28b3580694d7c32408b5448b4ff0a9fae72618c21695322c234be2c1b8b24f32a769a7e7ae
+  metadata.gz: ea4c88b70e03f9feb1a98886c1a04ae0f913f4c5a7de609b95215b12901b7530d9017d2f154c21c5893e7a10282e3bf8cd7ca005a068bab0aac1fe9b45139440
+  data.tar.gz: d4c0af7c25dbc3bc380b4793f82c5c172a4bfe3b2bff150310e4b9689d1e9c7f07a0be1833cd406c16dec0fce60f30032b95b4466dc93bd46059b0714ec0096d

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 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,236 @@
 # 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.
+
+## Rails
 
-To use it, add `masks` to your Gemfile or run:
+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.
 
-## Documentation
+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.
 
-Full documentation is available at [masks.geiger.to](https://masks.geiger.to).
+### An SPA in front of it
 
-## How it works
+`GET /auth/session` answers identity, tenant and scopes as JSON, or `401` with somewhere
+to send the browser. [`@masks/client`](../web) speaks it:
+
+```js
+import { createSession } from "@masks/client"
+
+const session = createSession()
+const status = await session.status()
+```
 
-At the heart of masks are a few key concepts:
+`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.
+
+### 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/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,87 @@
+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?
+
+        masks_registration&.delete
+
+        masks_config.forget!(request)
+        masks_forget
+
+        redirect_to masks_handshake_path
+      rescue Masks::Client::Error => e
+        refuse(e)
+      end
+
+      private
+
+        def masks_registration
+          Masks::Client::Registration.held(
+            masks_config.issuer_for(request),
+            masks_config.credentials_for(request)
+          )
+        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,113 @@
+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?
+
+        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::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>

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

@@ -0,0 +1,40 @@
+<% if @connected %>
+  <% content_for :title, "Reconnect this app" %>
+
+  <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">
+    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">Connect it</button>
+  <% end %>
+<% end %>