masks 0.9.2 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a915522b23f370321d7eca71a6d4965804d6988e441f6f019b1b1817bab7f0c3
-  data.tar.gz: 05f68f68ed521f6d378393cadda81bec7b984802f10ab651a5eaa8c9b31d4a7c
+  metadata.gz: e082a74bac3486cd6f3291ef29a91dd0ecc325a2f3938465a44722c66e2363b0
+  data.tar.gz: 22b5932157ba69c6c8401ab71b54ab0be1c640ae0f5da67f0ffa04c1fa1d15fa
 SHA512:
-  metadata.gz: 13467dcc61e51edbb9a7493feb38ccb2cf0f1f42db9a127cb37ccb89c0bf3187de211f928bce1dd854d711f3418a0b504bb3a2b0e645ee8ac7d864b47fd8d4c5
-  data.tar.gz: 4b0b6abea05f55b54b9280de48c8096a8406fdd82e7dcb575584b56679ccb91fc3af11c2766cda26cee44ae8ace19f384a5714a0e3a81b029bcead957d8ba008
+  metadata.gz: ed991af661f602ac3e32c190575bcb8f03f1f4ad5dce0d4006516ad2587e53efaa15c75b51a480b9ccbb1634f88844cc3a32ceb4c516313f93b928d01298d71f
+  data.tar.gz: ef37a84b598962d464d24c68e33db41645ab6e85be67b34d13bae1061f061db0ce2a0180d1b4e82ec77c98a17bfcdbee4812fd2a855783ae2868211e8ff54741

data/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## [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)
+
+
+### Features
+
+* **client:** a sign-in can ask for a step-up scope the app offers, and masks grants it only to people whose scopes cover it ([84b43d8](https://github.com/masksrb/masks/commit/84b43d8c091440a5a9b75721b56f9ced27c9f82f))
+* **client:** masked is the signed-in person in one object, read the same way from a session or a bearer token ([c2ad60c](https://github.com/masksrb/masks/commit/c2ad60cb5d2c795f2bf711e8650af5e1893aa0d2))
+* **client:** masks_require_scope! guards an action with a step-up scope, sending its holder through masks once and refusing everyone else ([fce327e](https://github.com/masksrb/masks/commit/fce327edae9d6166e8bc163d85c4ca8e6548e1eb))
+* **client:** privileges name what an action needs, and masked! checks them for a browser session or a bearer token alike ([97e998a](https://github.com/masksrb/masks/commit/97e998a68bf3365fc5ba72a99ca21cf66c6e500a))
+
 ## [0.9.2](https://github.com/masksrb/masks/compare/gem/v0.9.1...gem/v0.9.2) (2026-10-10)
 
 

data/README.md

@@ -22,7 +22,7 @@ bin/rails generate masks:install --resource https://app.example.com
 
 That mounts the engine at `/auth`, writes `config/initializers/masks.rb`, and gitignores
 the file credentials land in. Set `MASKS_ISSUER`, start the app, and open
-`/auth/handshake`. [Rails apps](https://masks.pages.dev/guides/rails/) walks through the rest.
+`/auth/handshake`. [Rails apps](https://masks.pages.dev/reference/ruby/) walks through the rest.
 
 ### The handshake
 
@@ -33,11 +33,12 @@ client secret never passes through the browser. The handshake registers the app
 asks before it rotates, because reconnecting takes it offline for a moment.
 
 Once an app is connected, only somebody `config.manages` approves can reconnect or disconnect it.
-The callable takes the request, or the request and the signed-in identity, and the engine refuses
-everyone when it is unset:
+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:
 
 ```ruby
-config.manages = ->(request, identity) { identity["sub"] == ENV["OWNER_SUB"] }
+config.manages = :admin
+config.manages = ->(request, masked) { masked.subject == ENV["OWNER_SUB"] }
 ```
 
 The engine writes what comes back to `config/masks.json`, mode 600. A multi-tenant app keeps it
@@ -54,16 +55,46 @@ config.store = ->(request, registration) { Tenant.for(request).connect!(registra
 class DashboardController < ApplicationController
   include Masks::Rails::Authentication
 
-  before_action :authenticate_masks!
+  masked!
 
   def index
-    @who = masks_identity
+    @who = masked.name
   end
 end
 ```
 
-`masks_identity`, `masks_tenant`, and `masks_scopes` describe the signed-in request. Tokens live in
-the encrypted Rails session and never reach JavaScript.
+`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/reference/ruby/#privileges).
 
 `config.authenticate_everything = true` includes `Authentication` on every controller. Otherwise
 include it where it applies.
@@ -71,7 +102,7 @@ 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:
+browser. [`@masks/client`](https://masks.pages.dev/reference/javascript/client/) reads it:
 
 ```js
 import { createSession } from "@masks/client"
@@ -91,7 +122,7 @@ An app that is also a resource server:
 class ApiController < ApplicationController
   include Masks::Rails::ProtectedResource
 
-  masks_protect! scope: "xixo:catalog:read", except: :metadata
+  masked! :read, except: :metadata
 
   def metadata
     render json: masks_resource_metadata
@@ -99,8 +130,8 @@ class ApiController < ApplicationController
 end
 ```
 
-`masks_protect!` installs the `before_action` and passes `:only` and `:except` through.
-`masks_claims` is the verified token. A refusal carries the RFC 6750 challenge with
+`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).
@@ -120,32 +151,28 @@ end
 class BillingController < ApplicationController
   include Masks::Rails::Authentication
 
-  masks_members_only! role: %w[owner billing]
+  masked! :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
+`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`.
 
-`masks_organizations` lists every organization the person has joined, each with the role held in
+`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
-<% masks_organizations.each do |held| %>
+<% masked.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: "xixo:catalog:write", role: "owner", organization: "acme"
-```
+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.
@@ -156,7 +183,7 @@ Every account has three avatars: an uploaded `photo`, an `identicon`, and two-le
 All three arrive on the ID token.
 
 ```erb
-<img src="<%= masks_claims.avatars.identicon %>?size=64" width="64" height="64" alt="">
+<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
@@ -166,7 +193,7 @@ app holds:
 <img src="/auth/avatar" width="64" height="64" alt="">
 ```
 
-`masks_claims.picture` is the standard OIDC `picture` claim when the account set one, then the photo,
+`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.
 
@@ -187,6 +214,7 @@ a subdomain-per-tenant host needs.
 | `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 |
@@ -197,6 +225,7 @@ a subdomain-per-tenant host needs.
 | `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 |
+| `replay` | where seen DPoP proofs are remembered, any object with `first?(key, expires_in:)`, this process's memory by default |
 
 ## Any Ruby app
 
@@ -221,14 +250,128 @@ Hold `started[:state]`, `started[:nonce]`, and `started[:verifier]` in the sessi
 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`.
+`Session` also has `refresh`, `exchange`, `client_credentials`, `device_authorization`,
+`await_device`, `enroll`, `unenroll`, `revoke`, `introspect`, `userinfo`, `end_session_url`, and
+`transport`. It authenticates with `client_secret`, or with `private_key` and `key_id` for
+`private_key_jwt`. A `Masks::Client::Key` passed as `private_key` names itself by its thumbprint, so
+`key_id` can be left out.
+
+`userinfo` takes `Tokens` or an access token string. A string and a `Bearer` token go as `Bearer`.
+A DPoP-bound token goes as `Authorization: DPoP` with a proof from the session's `dpop:` key, and
+raises `Masks::Client::Error` when the session holds no key.
+
+An app that has claimed a namespace enrolls a machine with `enroll`. It returns an
+`Enrollment` whose `initial_access_token` the machine spends once to register its own public key.
+
+```ruby
+enrollment = session.enroll(scope: "xixo:agent", name: "nas", expires_in: 900)
+enrollment.initial_access_token
+```
+
+`unenroll` takes the machine's client ID. masks archives the machine and revokes its tokens, and
+refuses a client the app did not enroll.
+
+```ruby
+session.unenroll(machine_client_id)
+```
+
+### A machine
+
+A machine enrolled by an app makes two P-256 keys: one to sign its client assertions, and one to
+hold its tokens with DPoP. It registers the public half of the first with the app's initial access
+token, and keeps both private halves to itself.
+
+```ruby
+key = Masks::Client::Key.generate
+dpop = Masks::Client::Key.generate
+
+registration = Masks::Client::Registration.create(
+  "https://demo.auth.example.com", token: initial_access_token,
+  name: "nas", jwks: key, token_endpoint_auth_method: "private_key_jwt",
+  grant_types: [ "client_credentials" ], dpop_bound_access_tokens: true
+)
+
+File.write("machine.json", { "client_id" => registration.client_id, "key" => key.to_h,
+                             "dpop" => dpop.to_h }.to_json, perm: 0o600)
+
+session = registration.session(private_key: key, dpop: dpop)
+tokens = session.client_credentials(scope: "xixo:agent")
+tokens.bound?
+```
+
+`Registration.create` sends `grant_types` and `response_types` only when they are given, and masks
+fills in the rest: an enrolled machine gets `client_credentials`, and an open registration gets
+`authorization_code` and `code`. `jwks:` takes a `Key`, a list of them, or a JWK Set. `Key#jwks` and `Key#public_jwk` hold only the
+public half, and `Key#to_h` holds the private one. `Key.parse` reads a key back from that hash, its
+JSON, or a PEM. A key on another curve, or a public key, raises `ArgumentError`.
+
+`Registration.create` with a `token:` posts to `/register` even when discovery publishes no
+`registration_endpoint`, because a tenant that turns open registration off still redeems initial
+access tokens there. `read`, `update`, and `delete` raise `Masks::Client::Foreign` when the
+`registration_client_uri` names an origin other than the issuer's, and send nothing.
+
+A `Session` given `dpop:` sends a new DPoP proof with every request to the token endpoint:
+`complete`, `client_credentials`, `refresh`, `exchange`, and `await_device`. A server that answers
+`use_dpop_nonce` with a `DPoP-Nonce` header gets one retry carrying that nonce, and the nonce is
+kept for that origin's next request. A token endpoint that answers a proven request with a `Bearer`
+token is refused with `invalid_dpop_proof`. Revocation, introspection, enrollment, and device
+authorization are sent without a proof.
+
+`transport` sends requests to a resource with those tokens. It takes the origins it may send them to
+and raises `Masks::Client::Foreign` for any other URL before it fetches a token. An origin in plain
+`http` follows the same rule as the issuer, and raises `Masks::Client::Insecure` when the transport
+is built. A resource's answers are not limited to 1 MB.
+
+```ruby
+api = session.transport("https://app.example.com", scope: "xixo:agent")
+
+response = api.get("https://app.example.com/mcp/feeds?page=2")
+api.post("https://app.example.com/mcp/feeds", body: { "name" => "notes" })
+```
+
+Each request carries `Authorization: DPoP` and a proof naming the method, the URL without its query,
+and the token's hash in `ath`. A resource that answers `401` with `use_dpop_nonce` in
+`WWW-Authenticate` and a new `DPoP-Nonce` is asked once more. The answer is a `Net::HTTPResponse`,
+which the transport returns whatever its status. A `Bearer` token goes as `Bearer` with no proof.
+
+Without `tokens:`, the transport asks for `client_credentials` with the `scope` and `resource` it was
+given, and again when they expire. With `tokens:`, it renews them with their refresh token, keeps that
+refresh token when the server does not rotate it, and yields the new tokens so they can be stored:
+
+```ruby
+api = session.transport("https://app.example.com", tokens: held) { |tokens| store(tokens.to_h) }
+```
+
+`Masks::Client::Transport.new(*origins, tokens:, key:)` builds one around tokens you already hold.
+
+### The device flow
+
+A device with no browser asks for a code, shows it, and polls until somebody approves it:
+
+```ruby
+device = session.device_authorization(scope: %w[openid offline_access], resource: "https://app.example.com/mcp")
+
+puts "Open #{device.verification_uri} and enter #{device.user_code}"
+
+tokens = session.await_device(device)
+```
+
+`await_device` waits `interval` seconds between polls, five when the server names none, and five
+seconds longer after each `slow_down`. It keeps polling through `authorization_pending`. It raises
+`Masks::Client::Rejected` with the server's code for `access_denied`, `expired_token`, or any other
+refusal, and raises `expired_token` without polling once `device.expires_at` has passed. A session
+holding a DPoP key proves each poll, and the tokens it returns are held to that key.
 
 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.
 
+Every request the gem makes goes over `https`, or plain `http` to `localhost`, a `*.localhost`
+name, or a loopback address. Any other `http` URL raises `Masks::Client::Insecure` before anything is
+sent. A deployment that reaches its issuer over a private network in plain `http` sets
+`Masks::Client.plain_http = true`. Answers from the issuer are read up to 1 MB, and an answer that
+is not a JSON object raises `Masks::Client::Rejected` with the code `invalid_response`.
+
 ### The handshake
 
 The flow that connects a first-party app:
@@ -269,8 +412,13 @@ claims.tenant.subdomain
 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.
+processes passes `replay:` to `Resource.new`, or sets `config.replay` in a Rails app, to any object
+whose `first?(key, expires_in:)` answers true only once for each key across every process.
+
+When that store raises, `authenticate` raises `Masks::Client::ReplayUnavailable`, which is not a
+challenge. The Rack middleware and a Rails controller answer `503` with `temporarily_unavailable`
+and no `WWW-Authenticate` header, so a client keeps a token that is still good. A proof the store
+has already seen is still refused with `401`.
 
 A refusal builds the RFC 6750 challenge carrying `resource_metadata` and the scopes it would have
 accepted:

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

@@ -22,7 +22,7 @@ module Masks
       private
 
         def photo_url
-          held = masks_claims.avatars.photo
+          held = masked.avatars.photo
 
           return nil if held.nil?
           return nil unless held.start_with?("#{masks_config.issuer_for(request)}/")

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

@@ -1,6 +1,7 @@
 module Masks
   module Rails
     class HandshakesController < BaseController
+      prepend_before_action :signed_out_upstream, only: :callback
       before_action :require_unconfigured_or_signed_in
       before_action :require_unconfigured_or_manager
 
@@ -44,6 +45,13 @@ module Masks
 
       private
 
+        def signed_out_upstream
+          return if params[:initial_access_token].present? || params[:error].present?
+          return stale if masks_farewells.claim(params[:state].to_s).nil?
+
+          redirect_to masks_after_sign_out_path
+        end
+
         def begin!
           pending = masks_handshakes.open
           started = masks_config.handshake_for(request).start(state: pending.id)
@@ -72,7 +80,7 @@ module Masks
 
         def require_unconfigured_or_manager
           return unless masks_config.configured?(request)
-          return if masks_config.manages?(request, masks_identity)
+          return if masks_config.manages?(request, masked)
 
           @code = "forbidden"
           @description = "only somebody this app lets manage its connection can reconnect or disconnect it"

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

@@ -8,7 +8,7 @@ module Masks
         if masks_configured? && (masks_signed_in? || (masks_tokens && masks_refresh!))
           response.headers["Cache-Control"] = "no-store"
 
-          render json: masks_account
+          render json: masked.to_h
         else
           masks_forget
           masks_refuse_json
@@ -25,6 +25,7 @@ module Masks
         started = masks_session.start(
           state: pending.id,
           resource: masks_config.resource_for(request),
+          scope: masks_config.scope_for(params[:privilege]),
           organization: Masks::Client::Session.organization_key(params[:organization]) ||
             masks_config.organization_for(request)
         )
@@ -72,12 +73,13 @@ 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
@@ -88,7 +90,7 @@ module Masks
       private
 
         def renew_session
-          carried = session.to_hash.slice(REQUESTS, HANDSHAKES)
+          carried = session.to_hash.slice(REQUESTS, HANDSHAKES, Masks::Rails::Authentication::STEPPED_UP)
 
           reset_session
           carried.each { |key, value| session[key] = value }

data/lib/masks/client/device.rb

@@ -0,0 +1,47 @@
+module Masks
+  module Client
+    class Device
+      GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code".freeze
+      INTERVAL = 5
+      REQUIRED = %w[device_code user_code verification_uri].freeze
+
+      attr_reader :device_code, :user_code, :verification_uri, :verification_uri_complete, :expires_in, :interval,
+                  :obtained_at
+
+      def self.issued(body)
+        missing = REQUIRED.find { |field| body[field].to_s.empty? }
+
+        if missing
+          raise Rejected.new(
+            body["error"] || "invalid_device_authorization_response",
+            body["error_description"] || "the device authorization endpoint answered without a #{missing}"
+          )
+        end
+
+        new(body)
+      end
+
+      def initialize(body)
+        @device_code = body["device_code"]
+        @user_code = body["user_code"]
+        @verification_uri = body["verification_uri"]
+        @verification_uri_complete = body["verification_uri_complete"]
+        @expires_in = body["expires_in"].to_i
+        @interval = body["interval"].to_i
+        @obtained_at = Time.now.to_i
+      end
+
+      def expires_at
+        obtained_at + expires_in
+      end
+
+      def expired?
+        Time.now.to_i > expires_at
+      end
+
+      def inspect
+        "#<#{self.class.name} #{user_code} for #{verification_uri}>"
+      end
+    end
+  end
+end

data/lib/masks/client/embedded.rb

@@ -0,0 +1,125 @@
+require "stringio"
+
+module Masks
+  module Client
+    class Embedded
+      LOOPBACK = "127.0.0.1".freeze
+      DROPPED = %w[host accept-encoding connection content-length].freeze
+
+      attr_reader :app
+
+      def initialize(app, &serves)
+        raise ArgumentError, "an embedded issuer needs the app that serves it" if app.nil?
+        raise ArgumentError, "an embedded issuer needs a block naming the URLs it serves" if serves.nil?
+
+        @app = app
+        @serves = serves
+      end
+
+      def serves?(uri)
+        @serves.call(uri) ? true : false
+      end
+
+      def deliver(request, limit: nil)
+        uri = request.uri
+        status, headers, body = answer(environment(request, uri), uri, limit)
+
+        parsed(request, raw(status, headers, body))
+      end
+
+      def inspect
+        "#<#{self.class.name} #{app.inspect}>"
+      end
+
+      private
+
+        def answer(env, uri, limit)
+          worker = Thread.new { collected(*app.call(env), uri, limit) }
+          worker.report_on_exception = false
+
+          unless worker.join(HTTP::READ_TIMEOUT)
+            worker.kill
+            raise Unreachable, "#{uri.host} did not answer within #{HTTP::READ_TIMEOUT} seconds"
+          end
+
+          worker.value
+        rescue Error
+          raise
+        rescue StandardError => e
+          raise Unreachable, "#{uri.host} failed inside this process (#{e.class})"
+        end
+
+        def collected(status, headers, body, uri, limit)
+          held = "".b
+
+          body.each do |chunk|
+            held << chunk.to_s.b
+            raise Error, "#{uri.host} answered with more than #{limit} bytes" if limit && held.bytesize > limit
+          end
+
+          [ status.to_i, headers, held ]
+        ensure
+          body.close if body.respond_to?(:close)
+        end
+
+        def environment(request, uri)
+          input = request.body.to_s.b
+
+          env = {
+            "REQUEST_METHOD" => request.method,
+            "SCRIPT_NAME" => "",
+            "PATH_INFO" => uri.path.to_s.empty? ? "/" : uri.path,
+            "QUERY_STRING" => uri.query.to_s,
+            "SERVER_NAME" => uri.host,
+            "SERVER_PORT" => uri.port.to_s,
+            "SERVER_PROTOCOL" => "HTTP/1.1",
+            "REMOTE_ADDR" => LOOPBACK,
+            "HTTP_HOST" => uri.port == uri.default_port ? uri.host : "#{uri.host}:#{uri.port}",
+            "HTTPS" => uri.scheme == "https" ? "on" : "off",
+            "rack.url_scheme" => uri.scheme,
+            "rack.input" => StringIO.new(input),
+            "rack.errors" => $stderr
+          }
+
+          env["CONTENT_LENGTH"] = input.bytesize.to_s unless input.empty?
+
+          request.each_header do |name, value|
+            next if DROPPED.include?(name)
+
+            key = name.upcase.tr("-", "_")
+            env[key == "CONTENT_TYPE" ? key : "HTTP_#{key}"] = value
+          end
+
+          env
+        end
+
+        def raw(status, headers, body)
+          lines = [ "HTTP/1.1 #{status} #{reason(status)}" ]
+
+          headers.each do |name, value|
+            next if %w[content-length transfer-encoding].include?(name.to_s.downcase)
+
+            Array(value).flat_map { |held| held.to_s.split(/\r?\n/) }.each { |held| lines << "#{name}: #{held}" }
+          end
+
+          lines << "content-length: #{body.bytesize}"
+
+          "#{lines.join("\r\n")}\r\n\r\n".b + body
+        end
+
+        def parsed(request, raw)
+          io = Net::BufferedIO.new(StringIO.new(raw))
+          response = Net::HTTPResponse.read_new(io)
+          response.uri = request.uri
+          response.reading_body(io, request.response_body_permitted?) { response.body }
+          response
+        end
+
+        def reason(status)
+          named = Net::HTTPResponse::CODE_TO_OBJ[status.to_s]
+
+          named ? named.name.delete_prefix("Net::HTTP").gsub(/(?<=[a-z])(?=[A-Z])/, " ") : "Unknown"
+        end
+    end
+  end
+end