masks 0.3.2 → 0.5.0

data/config/routes.rb

@@ -1,46 +1,11 @@
-# frozen_string_literal: true
-
-Masks::Engine.routes.draw do
-  get "/debug", to: "debug#show" if Rails.env.development?
-
-  # signup/login
-  get "session", to: "sessions#new", as: :session
-  post "session", to: "sessions#create"
-  delete "session", to: "sessions#destroy"
-
-  # recover credentials
-  get "recover", to: "recoveries#new", as: :recover
-  post "recover", to: "recoveries#create"
-  get "recovery", to: "recoveries#password", as: :recover_password
-  post "recovery", to: "recoveries#reset"
-
-  # manage account details, password, etc
-  get "me", to: "actors#current", as: :current
-  get "password", to: "passwords#edit", as: :password
-  post "password", to: "passwords#update"
-  post "device/:key", to: "devices#update", as: :device
-
-  # manage emails
-  get "emails", to: "emails#new", as: :emails
-  post "emails", to: "emails#create"
-  patch "emails", to: "emails#notify"
-  delete "emails", to: "emails#delete"
-  get "email/:email/verify", to: "emails#verify", as: :email_verify
-
-  # keys
-  get "keys", to: "keys#new", as: :keys
-  post "keys", to: "keys#create"
-  delete "keys", to: "keys#delete"
-
-  # manage 2nd factor options
-  get "one-time-codes", to: "one_time_code#new", as: :one_time_code
-  post "one-time-codes", to: "one_time_code#create"
-  delete "one-time-codes", to: "one_time_code#destroy"
-  get "backup-codes", to: "backup_codes#new", as: :backup_codes
-  post "backup-codes", to: "backup_codes#create"
-
-  # managers-only section
-  get "actors", to: "manage/actors#index", as: :actors
-  get "actors/:actor", to: "manage/actor#show", as: :actor
-  patch "actors/:actor", to: "manage/actor#update"
+Masks::Rails::Engine.routes.draw do
+  get "/", to: "sessions#start", as: :start
+  get "/session", to: "sessions#show", as: :session
+  get "/callback", to: "sessions#callback", as: :callback
+  match "/logout", to: "sessions#destroy", via: %i[get post delete], as: :logout
+
+  get "/handshake", to: "handshakes#show", as: :handshake
+  post "/handshake", to: "handshakes#create"
+  get "/handshake/callback", to: "handshakes#callback", as: :handshake_callback
+  delete "/handshake", to: "handshakes#destroy"
 end

data/lib/generators/masks/install/install_generator.rb

@@ -1,33 +1,46 @@
-# frozen_string_literal: true
+require "rails/generators/base"
 
 module Masks
-  # Generator for +rails g masks:install+.
-  class InstallGenerator < ::Rails::Generators::Base
-    source_root File.expand_path("templates", __dir__)
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
 
-    def add_routing
-      route 'mount Masks::Engine => "/"'
-    end
+      desc "Mount the masks engine, write an initializer, and say what to set."
 
-    def copy_initializer_file
-      copy_file "initializer.rb", "config/initializers/masks.rb"
-    end
+      class_option :mount, type: :string, default: "/auth",
+                   desc: "Where to mount the engine"
+      class_option :resource, type: :string, default: nil,
+                   desc: "This app's resource identifier, if it is also a resource server"
 
-    def copy_masks_json
-      copy_file "masks.json", "masks.json"
-    end
+      def create_initializer
+        @mount_path = options[:mount]
+        @resource = options[:resource]
+
+        template "masks.rb.tt", "config/initializers/masks.rb"
+      end
+
+      def mount_engine
+        route %(mount Masks::Rails::Engine, at: "#{options[:mount]}")
+      end
 
-    def add_migrations
-      if yes?("generate migrations for masks?")
-        rails_command "masks:install:migrations"
-      else
-        puts
-        puts 'run "rails masks:install:migrations" to add them later on...'
+      def ignore_credentials
+        append_to_file ".gitignore", "\n# masks: what the handshake gave this app\n/config/masks.json\n"
       end
 
-      puts
-      puts "[masks] welcome!"
-      puts "[masks] visit https://masks.geiger.to for more information."
+      def say_what_is_left
+        say ""
+        say "masks is mounted at #{options[:mount]}.", :green
+        say ""
+        say "  1. Set MASKS_ISSUER in the environment, or edit the initializer."
+        say "  2. Start the app and open #{options[:mount]}/handshake."
+        say "  3. Approve it at your masks server. The credentials land in"
+        say "     config/masks.json, which the generator has gitignored."
+        say ""
+        say "Include Masks::Rails::Authentication in the controllers that want"
+        say "it, or set config.authenticate_everything = true to have it on all"
+        say "of them. Nothing is included for you."
+        say ""
+      end
     end
   end
 end

data/lib/generators/masks/install/templates/masks.rb.tt

@@ -0,0 +1,38 @@
+Masks::Rails.configure do |config|
+  # The issuer this app signs in against. A callable taking the request works
+  # too, which is what a subdomain-per-tenant host needs.
+  config.issuer = ENV.fetch("MASKS_ISSUER", "https://auth.example.com")
+<% if @resource -%>
+
+  # This app is also a resource server: the identifier tokens are minted for,
+  # and the scopes it accepts. It is what `resource=` sends at authorize and
+  # what `aud` is checked against.
+  config.resource = "<%= @resource %>"
+  config.resource_scopes = []
+<% else -%>
+
+  # Uncomment when this app also accepts tokens of its own. `resource` is the
+  # identifier tokens are minted for; `resource_scopes` are what it accepts.
+  # config.resource = "https://app.example.com/api"
+  # config.resource_scopes = []
+<% end -%>
+
+  # Where to land after each. Both must be paths on this host.
+  config.after_sign_in = "/"
+  config.after_sign_out = "/"
+
+  # Credentials arrive from the handshake and are kept in config/masks.json.
+  # Replace both with your own storage when one file is not the right shape —
+  # a multi-tenant app wants a row per tenant rather than a file per install.
+  #
+  # config.credentials = ->(request) { Tenant.for(request).masks_credentials }
+  # config.store = ->(request, registration) { Tenant.for(request).connect!(registration) }
+
+  # Signing out of this app does not sign you out of the issuer unless you say
+  # so. Leave it false and offer "sign out everywhere" as its own action.
+  # config.sign_out_of_issuer = false
+
+  # The engine's pages inherit this, so a consumer's layout, helpers and
+  # before_actions apply to them.
+  # config.parent_controller = "ApplicationController"
+end

data/lib/masks/client/claims.rb

@@ -0,0 +1,103 @@
+module Masks
+  module Client
+    class Claims
+      class Tenant
+        attr_reader :to_h
+
+        def initialize(hash)
+          @to_h = hash.is_a?(Hash) ? hash : {}
+        end
+
+        def uuid
+          to_h["uuid"]
+        end
+
+        def subdomain
+          to_h["subdomain"]
+        end
+
+        def name
+          to_h["name"]
+        end
+
+        def present?
+          !uuid.nil? || !subdomain.nil?
+        end
+
+        def ==(other)
+          other.is_a?(Tenant) ? to_h == other.to_h : false
+        end
+      end
+
+      attr_reader :to_h
+
+      def initialize(claims)
+        @to_h = claims
+      end
+
+      def [](name)
+        to_h[name.to_s]
+      end
+
+      def subject
+        self["sub"]
+      end
+
+      def issuer
+        self["iss"]
+      end
+
+      def audience
+        Array(self["aud"])
+      end
+
+      def client_id
+        self["client_id"]
+      end
+
+      def jti
+        self["jti"]
+      end
+
+      def act
+        self["act"]
+      end
+
+      def tenant
+        @tenant ||= Tenant.new(self["tenant"])
+      end
+
+      def scopes
+        @scopes ||= self["scope"].to_s.split(/\s+/).reject(&:empty?).freeze
+      end
+
+      def permits?(scope)
+        scopes.include?(scope.to_s)
+      end
+
+      def permit!(scope)
+        return true if permits?(scope)
+
+        raise Forbidden.new(
+          "insufficient_scope",
+          "this token does not carry #{scope}",
+          scope: scope.to_s
+        )
+      end
+
+      def expires_at
+        @expires_at ||= self["exp"] && Time.at(self["exp"])
+      end
+
+      def issued_at
+        @issued_at ||= self["iat"] && Time.at(self["iat"])
+      end
+
+      def expired?(leeway: 0)
+        return false if expires_at.nil?
+
+        Time.now.to_i + leeway >= expires_at.to_i
+      end
+    end
+  end
+end

data/lib/masks/client/errors.rb

@@ -0,0 +1,52 @@
+module Masks
+  module Client
+    class Error < StandardError; end
+
+    class Unreachable < Error; end
+
+    class Rejected < Error
+      attr_reader :code, :description, :status
+
+      def initialize(code, description, status: nil)
+        super([ code, description ].compact.join(": "))
+
+        @code = code
+        @description = description
+        @status = status
+      end
+    end
+
+    class InvalidToken < Error; end
+
+    class Challenge < Error
+      attr_reader :code, :description, :status, :scope
+
+      def initialize(code, description, status:, scope: nil)
+        super([ code, description ].compact.join(": "))
+
+        @code = code
+        @description = description
+        @status = status
+        @scope = scope
+      end
+    end
+
+    class Unauthenticated < Challenge
+      def initialize(description = "a bearer token is required", code: nil)
+        super(code, description, status: 401)
+      end
+    end
+
+    class Unauthorized < Challenge
+      def initialize(description, code: "invalid_token")
+        super(code, description, status: 401)
+      end
+    end
+
+    class Forbidden < Challenge
+      def initialize(code, description, scope: nil)
+        super(code, description, status: 403, scope: scope)
+      end
+    end
+  end
+end

data/lib/masks/client/handshake.rb

@@ -0,0 +1,104 @@
+module Masks
+  module Client
+    class Handshake
+      PATH = "/handshake".freeze
+      GRANT_TYPES = %w[authorization_code refresh_token].freeze
+      AUTH_METHOD = "client_secret_basic".freeze
+
+      attr_reader :issuer, :name, :resource, :redirect_uris, :scope, :return_to
+
+      def initialize(issuer, name:, resource:, redirect_uris:, return_to:,
+                     scope: Session::DEFAULT_SCOPE)
+        @issuer = Issuer.resolve(issuer)
+        @name = name.to_s
+        @resource = resource.to_s
+        @redirect_uris = Array(redirect_uris).map(&:to_s)
+        @scope = Array(scope).flat_map { |value| value.to_s.split(/\s+/) }.reject(&:empty?)
+        @return_to = return_to.to_s
+      end
+
+      def endpoint
+        @endpoint ||= advertised || "#{issuer.url}#{PATH}"
+      end
+
+      def start(state: SecureRandom.urlsafe_base64(32))
+        { url: url(state: state), state: state }
+      end
+
+      def url(state:)
+        query = [
+          [ "client_name", name ],
+          [ "resource", resource ],
+          [ "scope", scope.join(" ") ],
+          [ "return_to", return_to ],
+          [ "state", state ]
+        ]
+
+        redirect_uris.each { |uri| query << [ "redirect_uris", uri ] }
+
+        "#{endpoint}?#{URI.encode_www_form(query)}"
+      end
+
+      def complete(params, state:)
+        held = normalize(params)
+
+        refuse(held["error"], held["error_description"]) if present?(held["error"])
+        verify_state!(held["state"], state)
+        verify_issuer!(held["iss"])
+
+        redeem(held["initial_access_token"])
+      end
+
+      def redeem(token)
+        unless present?(token)
+          refuse("invalid_request", "the handshake came back without a token")
+        end
+
+        Registration.create(
+          issuer,
+          token: token,
+          name: name,
+          redirect_uris: redirect_uris,
+          grant_types: GRANT_TYPES,
+          scope: scope,
+          token_endpoint_auth_method: AUTH_METHOD
+        )
+      end
+
+      private
+
+        def advertised
+          value = issuer.discovery["handshake_endpoint"]
+          present?(value) ? value.to_s : nil
+        rescue Masks::Client::Error
+          nil
+        end
+
+        def verify_state!(returned, held)
+          return if present?(held) && present?(returned) &&
+                    OpenSSL.secure_compare(returned.to_s, held.to_s)
+
+          refuse("invalid_state", "the handshake did not match this browser")
+        end
+
+        def verify_issuer!(named)
+          return unless present?(named)
+          return if Issuer.normalize(named) == issuer.url
+
+          refuse("invalid_issuer", "that came back from #{named} rather than #{issuer.url}")
+        end
+
+        def refuse(code, description)
+          raise Rejected.new(code.to_s, description.to_s)
+        end
+
+        def normalize(params)
+          params.to_h.each_with_object({}) { |(key, value), held| held[key.to_s] = value }
+        end
+
+        def present?(value)
+          !value.nil? && !value.to_s.empty?
+        end
+    end
+  end
+end

data/lib/masks/client/http.rb

@@ -0,0 +1,81 @@
+module Masks
+  module Client
+    module HTTP
+      OPEN_TIMEOUT = 5
+      READ_TIMEOUT = 10
+
+      module_function
+
+      def get(url, headers = {})
+        request(Net::HTTP::Get.new(URI.parse(url.to_s), default_headers.merge(headers)))
+      end
+
+      def post_form(url, form, headers = {})
+        uri = URI.parse(url.to_s)
+        request = Net::HTTP::Post.new(uri, default_headers.merge(headers))
+        request.body = URI.encode_www_form(form)
+        request["Content-Type"] = "application/x-www-form-urlencoded"
+
+        self.request(request)
+      end
+
+      def post_json(url, body, headers = {})
+        json(Net::HTTP::Post, url, body, headers)
+      end
+
+      def put_json(url, body, headers = {})
+        json(Net::HTTP::Put, url, body, headers)
+      end
+
+      def delete(url, headers = {})
+        request(Net::HTTP::Delete.new(URI.parse(url.to_s), default_headers.merge(headers)))
+      end
+
+      def json(verb, url, body, headers)
+        uri = URI.parse(url.to_s)
+        request = verb.new(uri, default_headers.merge(headers))
+        request.body = JSON.generate(body)
+        request["Content-Type"] = "application/json"
+
+        self.request(request)
+      end
+
+      def default_headers
+        { "Accept" => "application/json", "User-Agent" => "masks/#{Masks::VERSION}" }
+      end
+
+      def request(request)
+        uri = request.uri
+
+        response = Net::HTTP.start(
+          uri.hostname, uri.port,
+          use_ssl: uri.scheme == "https",
+          open_timeout: OPEN_TIMEOUT,
+          read_timeout: READ_TIMEOUT
+        ) { |http| http.request(request) }
+
+        parse(response)
+      rescue SystemCallError, SocketError, Net::OpenTimeout, Net::ReadTimeout, OpenSSL::SSL::SSLError => e
+        raise Unreachable, "#{uri.host} is unreachable (#{e.class})"
+      end
+
+      def parse(response)
+        body = begin
+          JSON.parse(response.body.to_s)
+        rescue JSON::ParserError
+          {}
+        end
+
+        unless response.is_a?(Net::HTTPSuccess)
+          raise Rejected.new(
+            body["error"] || "http_#{response.code}",
+            body["error_description"] || response.message,
+            status: response.code.to_i
+          )
+        end
+
+        body
+      end
+    end
+  end
+end

data/lib/masks/client/introspection.rb

@@ -0,0 +1,29 @@
+module Masks
+  module Client
+    class Introspection < Claims
+      def active?
+        to_h["active"] == true
+      end
+
+      def username
+        self["username"]
+      end
+
+      def token_type
+        self["token_type"]
+      end
+
+      def permits?(scope)
+        active? && super
+      end
+
+      def permit!(scope)
+        unless active?
+          raise Unauthorized.new("the issuer reports this token is not active")
+        end
+
+        super
+      end
+    end
+  end
+end

data/lib/masks/client/issuer.rb

@@ -0,0 +1,76 @@
+module Masks
+  module Client
+    class Issuer
+      DISCOVERY_PATH = "/.well-known/openid-configuration".freeze
+      TTL = 300
+
+      def self.normalize(url)
+        url.to_s.chomp("/")
+      end
+
+      def self.resolve(issuer, ttl: TTL)
+        return issuer if issuer.is_a?(self)
+
+        Masks::Client.registry[issuer, ttl: ttl]
+      end
+
+      attr_reader :url
+
+      def initialize(url, ttl: TTL)
+        @url = self.class.normalize(url)
+        @ttl = ttl
+        @cache = {}
+        @lock = Mutex.new
+      end
+
+      def discovery
+        fetch(:discovery) do
+          document = HTTP.get("#{url}#{DISCOVERY_PATH}")
+          named = self.class.normalize(document["issuer"])
+
+          unless named == url
+            raise Rejected.new(
+              "invalid_issuer",
+              "#{url} publishes a document naming #{document['issuer'].inspect}"
+            )
+          end
+
+          document
+        end
+      end
+
+      def jwks
+        fetch(:jwks) { HTTP.get(endpoint("jwks_uri")) }
+      end
+
+      def tenant
+        discovery["tenant"]
+      end
+
+      def endpoint(name)
+        discovery.fetch(name) { raise Rejected.new("invalid_issuer", "#{url} publishes no #{name}") }
+      end
+
+      def refresh!
+        @lock.synchronize { @cache = {} }
+        self
+      end
+
+      private
+
+        def fetch(key)
+          cached = @lock.synchronize { @cache[key] }
+          return cached[:value] if fresh?(cached)
+
+          value = yield
+
+          @lock.synchronize { @cache[key] = { value: value, at: Time.now.to_i } }
+          value
+        end
+
+        def fresh?(entry)
+          entry && entry[:at] + @ttl > Time.now.to_i
+        end
+    end
+  end
+end

data/lib/masks/client/pkce.rb

@@ -0,0 +1,27 @@
+module Masks
+  module Client
+    class Pkce
+      METHOD = "S256".freeze
+
+      attr_reader :verifier
+
+      def self.generate
+        new(SecureRandom.urlsafe_base64(64))
+      end
+
+      def initialize(verifier)
+        @verifier = verifier
+      end
+
+      def challenge
+        Base64.urlsafe_encode64(
+          OpenSSL::Digest::SHA256.digest(verifier), padding: false
+        )
+      end
+
+      def method
+        METHOD
+      end
+    end
+  end
+end