ruby_everywhere 0.3.0 → 0.5.0

data/lib/everywhere/auth_handoff.rb

@@ -0,0 +1,404 @@
+# frozen_string_literal: true
+
+require "rack/utils"
+require "time"
+require_relative "auth_token"
+require_relative "config"
+
+module Everywhere
+  # Third-party sign-in for the native shells, as Rack middleware.
+  #
+  # Google refuses OAuth in an embedded web view outright, and Apple and GitHub
+  # are only marginally better there (no password manager, no already-signed-in
+  # session, 2FA that fights the keyboard). So the shell doesn't use its web
+  # view: it hands provider paths to an ASWebAuthenticationSession — the
+  # system's own browser, sharing Safari's cookies — and this middleware bridges
+  # the two jars, because the session cookie the flow ends with lands in the
+  # browser's jar and the app's web view can never read it.
+  #
+  #   1. shell opens  /everywhere/auth/start?to=/auth/github   (auth browser)
+  #      → marker cookie, redirect to the app's own provider path
+  #   2. the app's normal OAuth runs — OmniAuth, or whatever it uses — and
+  #      redirects somewhere signed in
+  #   3. this middleware catches that redirect, seals the resulting cookie jar
+  #      into a short-lived token, and redirects to <scheme>://auth?token=…,
+  #      which is the callback ASWebAuthenticationSession is waiting for
+  #   4. the shell visits /everywhere/auth/handoff?token=… in its web view,
+  #      which replays the jar there and lands on the app's post-auth page
+  #
+  # The app's auth is untouched: nothing here knows a provider from a hole in
+  # the ground, only which paths `auth.oauth_paths` says start a flow.
+  #
+  # Rails apps get this from Everywhere::Engine (at the top of the middleware
+  # stack, above any OmniAuth-family middleware). Sinatra/Hanami add it in
+  # config.ru — first, for the same reason — alongside the config endpoint:
+  #
+  #   use Everywhere::AuthHandoff
+  #   use Everywhere::MobileConfigEndpoint
+  #
+  # Apps on OmniAuth 2 also need Everywhere::OmniAuth.protect! — see
+  # everywhere/omniauth.rb for why its POST-only request phase and this flow
+  # have to be introduced to each other.
+  class AuthHandoff
+    START = "/everywhere/auth/start"
+    NATIVE = "/everywhere/auth/native"
+    HANDOFF = "/everywhere/auth/handoff"
+
+    # Set by START, read on the way back out. Ours, not the app's session: it
+    # must survive whatever the app does to its own session mid-flow, and it
+    # must be droppable from the jar we replay.
+    MARKER_COOKIE = "_everywhere_auth"
+    MARKER_PURPOSE = "everywhere/auth-marker"
+    HANDOFF_PURPOSE = "everywhere/auth-handoff"
+
+    # How long a started flow stays interceptable. Long enough for a password
+    # manager, a 2FA code and a slow provider; short enough that an abandoned
+    # flow can't divert an ordinary browser session later.
+    MARKER_TTL = 900
+
+    def initialize(app, root: Dir.pwd)
+      @app = app
+      @root = root
+      @mutex = Mutex.new
+    end
+
+    def call(env)
+      config = config_for(env)
+      return @app.call(env) unless config&.oauth?
+
+      case env["PATH_INFO"]
+      when START then return start(env, config)
+      when NATIVE then return native_page(env)
+      when HANDOFF then return handoff(env, config)
+      end
+
+      divert(env, config) || finish(env, config)
+    end
+
+    private
+
+    # GET /everywhere/auth/start?to=/auth/github&return_to=/settings
+    #
+    # The first page of the auth browser. Marks the jar as ours and continues
+    # into the app's own provider path — `to` is only honored when it's a path
+    # the config already calls a provider path, so this can't be turned into an
+    # open redirect.
+    def start(env, config)
+      return redirect("/") if cross_site?(env)
+
+      params = query(env)
+      to = same_origin_path(params["to"], env)
+      return redirect("/") unless to && config.oauth_path?(to.split("?").first)
+
+      marker = AuthToken.encrypt({ "return_to" => same_origin_path(params["return_to"], env) || "/",
+                                   "iat" => Time.now.to_i },
+                                 purpose: MARKER_PURPOSE, ttl: MARKER_TTL)
+      redirect(to, cookies: [marker_cookie(marker, env, max_age: MARKER_TTL)])
+    end
+
+    # A cross-site visit must not seed a sign-in: a fresh marker is what the
+    # OmniAuth request validator (everywhere/omniauth.rb) accepts a GET request
+    # phase on, so start would otherwise be the CSRF hole POST-only request
+    # phases closed. The shell opens this URL itself — browsers stamp that
+    # Sec-Fetch-Site: none — and only an explicit cross-site initiator or a
+    # subresource load is refused, so browsers too old for the headers lose
+    # nothing.
+    def cross_site?(env)
+      return true if env["HTTP_SEC_FETCH_SITE"] == "cross-site"
+
+      dest = env["HTTP_SEC_FETCH_DEST"]
+      !dest.nil? && dest != "document"
+    end
+
+    # GET /everywhere/auth/native?to=/auth/github
+    #
+    # The page that asks the shell to open the auth session. Only reached when
+    # the shell couldn't divert the visit itself (see #divert).
+    def native_page(env)
+      html(Everywhere.mobile_auth_html(query(env)["to"]))
+    end
+
+    # GET /everywhere/auth/handoff?token=…
+    #
+    # Visited in the app's web view: replays the sealed jar there, then sends
+    # the app on to wherever its own sign-in wanted to go. A token that doesn't
+    # verify lands on the root signed out rather than erroring — by then the
+    # user has done everything right, and the honest answer is the app.
+    def handoff(env, config)
+      payload = AuthToken.decrypt(query(env)["token"], purpose: HANDOFF_PURPOSE, once: true)
+      return redirect("/") unless payload
+
+      jar = payload["cookies"]
+      expiries = payload["expires"].is_a?(Hash) ? payload["expires"] : {}
+      cookies = jar.is_a?(Hash) ? jar.filter_map { |name, value| replayed_cookie(name, value, expiries[name], env) } : []
+      redirect(same_origin_path(payload["to"], env) || "/", cookies: cookies)
+    end
+
+    # One cookie on its way into the web view's jar. A lifetime the flow saw
+    # (Set-Cookie Max-Age/Expires) carries over — a remember-me cookie replayed
+    # session-scoped would sign the user out at the next app launch. Cookies
+    # the flow only ever saw in a request header stay session-scoped: their
+    # lifetime is unknowable from there.
+    def replayed_cookie(name, value, expires_at, env)
+      return cookie(name, value, env) unless expires_at
+
+      remaining = expires_at.to_i - Time.now.to_i
+      return nil unless remaining.positive?
+
+      cookie(name, value, env, max_age: remaining)
+    end
+
+    # A provider path requested from inside the shell's web view — the visits
+    # the shell couldn't intercept natively (a `data-turbo="false"` link, or the
+    # POST that OmniAuth 2 requires). Bounce to a page that can ask it to.
+    #
+    # mobile_platform_of, not native_platform_of: the whole handoff exists
+    # because a phone shell must open the provider in ASWebAuthenticationSession
+    # / Custom Tabs. The desktop shell already sends external links to the system
+    # browser, so diverting there would bounce sign-in to a page nothing can
+    # complete.
+    def divert(env, config)
+      return nil unless Everywhere.mobile_platform_of(env["HTTP_USER_AGENT"])
+      return nil unless config.oauth_path?(env["PATH_INFO"])
+
+      redirect("#{NATIVE}?#{Rack::Utils.build_query("to" => path_with_query(env))}")
+    end
+
+    # The flow is over the moment it navigates back out of the provider paths:
+    # the app's callback has redirected somewhere signed in, and the browser is
+    # asking for that page. That's the request we take.
+    #
+    # One hop later than the callback's own redirect, deliberately. The cookies
+    # are the whole point of this, and by here they're in the request — where
+    # every framework agrees they are. In the callback's *response* they may not
+    # be yet: Rails writes Set-Cookie in ActionDispatch::Cookies, and whether
+    # this middleware sees that depends on where the app put it in the stack —
+    # a thing the flow must not be sensitive to.
+    def finish(env, config)
+      # Only ever the auth browser: inside the web view the app is already
+      # holding the jar we would be handing it, and a stale marker there must
+      # not divert an ordinary visit into a callback URL it can't open.
+      marker = auth_marker(env) unless Everywhere.mobile_platform_of(env["HTTP_USER_AGENT"])
+      return @app.call(env) if marker.nil? || config.oauth_path?(env["PATH_INFO"]) || !navigation?(env)
+
+      _, headers, body = @app.call(env)
+      body.close if body.respond_to?(:close) # dropped: the browser gets the callback instead
+
+      close(env, config, headers, to: path_with_query(env), return_to: marker["return_to"])
+    end
+
+    # A top-level page load, as opposed to the stylesheet a provider's own
+    # consent screen pulls in — same-origin for us only by accident, and not
+    # the user arriving back signed in.
+    def navigation?(env)
+      env["REQUEST_METHOD"] == "GET" && env["HTTP_ACCEPT"].to_s.include?("text/html")
+    end
+
+    # Seal what the flow ended up with and return through the callback scheme.
+    # The jar is captured raw — verbatim values, straight from the request's
+    # Cookie header and any Set-Cookie on the way past — so whatever the app's
+    # auth library signed or encrypted arrives in the web view byte for byte.
+    def close(env, config, headers, to:, return_to:)
+      jar = request_jar(env)
+      expiries = apply_set_cookies(jar, headers)
+      jar.delete(MARKER_COOKIE)
+      jar.select! { |name, _| config.auth_cookie?(name) }
+      expiries.select! { |name, _| jar.key?(name) }
+
+      # The app's destination wins, except where it has no opinion: a sign-in
+      # that lands on the root usually meant "wherever you were", and in the
+      # auth browser the app has no stored location to remember that from.
+      target = to == "/" && return_to ? return_to : to
+      payload = { "cookies" => jar, "to" => target }
+      payload["expires"] = expiries unless expiries.empty?
+      token = AuthToken.encrypt(payload, purpose: HANDOFF_PURPOSE, ttl: config.auth_token_ttl)
+
+      # The browser jar keeps what it earned (the user is signed in in Safari
+      # too, as with any ASWebAuthenticationSession) minus our marker.
+      cookies = Array(header_values(headers, "set-cookie")) + [marker_cookie("", env, max_age: 0)]
+      redirect("#{config.auth_scheme}://auth?#{Rack::Utils.build_query("token" => token)}", cookies: cookies)
+    end
+
+    # MARK: config
+
+    # everywhere.yml, re-read only when it changes on disk. This middleware sees
+    # every request in the app, so the config endpoint's load-per-request would
+    # be a YAML parse in the way of each one.
+    #
+    # A save that doesn't parse must not take the site down from inside a
+    # middleware that wraps every request: keep the last good config — or none,
+    # on a first load — and say so, once per bad save.
+    def config_for(_env)
+      path = File.join(@root, Config::FILE)
+      mtime = File.mtime(path) if File.exist?(path)
+      return @config if defined?(@config) && @mtime == mtime
+
+      @mutex.synchronize do
+        return @config if defined?(@config) && @mtime == mtime
+
+        loaded = begin
+          Config.load(@root)
+        rescue StandardError => e
+          kept = defined?(@config) && @config ? "keeping the previous configuration" : "native sign-in is off until it loads"
+          warn "everywhere: #{Config::FILE} could not be loaded (#{e.message}); #{kept}"
+          defined?(@config) ? @config : nil
+        end
+        @mtime = mtime
+        @config = loaded
+      end
+    end
+
+    # MARK: request/response plumbing
+
+    def query(env) = Rack::Utils.parse_query(env["QUERY_STRING"])
+
+    def path_with_query(env)
+      query = env["QUERY_STRING"].to_s
+      query.empty? ? env["PATH_INFO"] : "#{env["PATH_INFO"]}?#{query}"
+    end
+
+    def auth_marker(env)
+      self.class.marker(env)
+    end
+
+    def redirect(location, cookies: [])
+      headers = { "location" => location, "cache-control" => "no-store", "content-type" => "text/html" }
+      headers = set_cookie(headers, cookies)
+      [302, canonical(headers), ["<html><body>Redirecting…</body></html>"]]
+    end
+
+    def html(body)
+      [200, canonical({ "content-type" => "text/html; charset=utf-8", "cache-control" => "no-store" }), [body]]
+    end
+
+    # Rack 3 requires lowercase header names; Rack 2's ecosystem looks names up
+    # in the classic case (servers are forgiving, middlewares are not).
+    def canonical(headers)
+      return headers if rack3?
+
+      headers.transform_keys { |name| name.split("-").map(&:capitalize).join("-") }
+    end
+
+    # Rack 3 wants set-cookie as an array; Rack 2 wants one newline-joined
+    # string. Both are the same list of cookie lines either way.
+    def set_cookie(headers, cookies)
+      values = Array(cookies).reject { |c| c.to_s.empty? }
+      return headers if values.empty?
+
+      headers.merge("set-cookie" => rack3? ? values : values.join("\n"))
+    end
+
+    # Rack::Headers arrived with Rack 3 — and version constants aren't loaded by
+    # rack/utils alone, so the class is the reliable tell.
+    def rack3? = defined?(Rack::Headers) ? true : false
+
+    def header_values(headers, name)
+      value = headers[name] || headers[name.split("-").map(&:capitalize).join("-")]
+      value.is_a?(String) ? value.split("\n") : value
+    end
+
+    # A same-origin path (with query), or nil. Absolute URLs are accepted only
+    # for the app's own host — everything here ends up in a Location header or
+    # a redirect target.
+    def same_origin_path(value, env)
+      path = value.to_s
+      return nil if path.empty?
+
+      if (match = path.match(%r{\Ahttps?://([^/]+)(/.*)?\z}i))
+        return nil unless match[1].casecmp?(env["HTTP_HOST"].to_s)
+
+        path = match[2].to_s
+        path = "/" if path.empty?
+      end
+      path if path.start_with?("/") && !path.start_with?("//")
+    end
+
+    # MARK: cookies
+
+    def request_jar(env)
+      self.class.request_jar(env)
+    end
+
+    class << self
+      # The request's cookies, values left exactly as they arrived — re-escaping
+      # a decoded value would corrupt any cookie the app didn't escape the same
+      # way. First occurrence wins on a duplicate name, matching Rack's parser
+      # (browsers send the most specific cookie first), so the jar sealed here
+      # is the jar the app actually read.
+      def request_jar(env)
+        env["HTTP_COOKIE"].to_s.split(/;\s*/).each_with_object({}) do |pair, jar|
+          name, value = pair.split("=", 2)
+          next if name.nil? || value.nil?
+
+          name = name.strip
+          jar[name] = value unless jar.key?(name)
+        end
+      end
+
+      # The start marker riding a request, decrypted, or nil. Class-level
+      # because the OmniAuth request validator (everywhere/omniauth.rb) asks
+      # the same question of the same cookie.
+      def marker(env)
+        raw = request_jar(env)[MARKER_COOKIE] or return nil
+
+        AuthToken.decrypt(Rack::Utils.unescape(raw), purpose: MARKER_PURPOSE)
+      end
+    end
+
+    # Fold a response's Set-Cookie headers into the jar, honoring deletions —
+    # a sign-out mid-flow must not hand the app a session it just discarded.
+    # Returns when each surviving cookie expires ({name => unix time}, only
+    # the ones that said): the response is the flow's one chance to learn a
+    # lifetime, and what keeps a remember-me cookie from crossing into the
+    # web view session-scoped.
+    def apply_set_cookies(jar, headers)
+      expiries = {}
+      Array(header_values(headers, "set-cookie")).each do |line|
+        pair, *attributes = line.to_s.split(/;\s*/)
+        name, value = pair.to_s.split("=", 2)
+        next if name.nil? || value.nil?
+
+        name = name.strip
+        expiry = expiry_of(attributes)
+        if value.empty? || (expiry && expiry <= Time.now.to_i)
+          jar.delete(name)
+          expiries.delete(name)
+        else
+          jar[name] = value
+          expiries[name] = expiry if expiry
+        end
+      end
+      expiries
+    end
+
+    # When the cookie line says it expires (unix time), nil for session scope.
+    # Max-Age wins over Expires, per RFC 6265.
+    def expiry_of(attributes)
+      expires = nil
+      attributes.each do |attribute|
+        key, value = attribute.split("=", 2)
+        case key.to_s.downcase
+        when "max-age" then return Time.now.to_i + value.to_i
+        when "expires" then expires = (Time.httpdate(value.to_s).to_i rescue nil)
+        end
+      end
+      expires
+    end
+
+    def marker_cookie(value, env, max_age:)
+      cookie(MARKER_COOKIE, value, env, max_age: max_age)
+    end
+
+    # Rebuilt rather than replayed attribute-for-attribute: a request's Cookie
+    # header carries names and values only, so the flags are ours to choose.
+    # HttpOnly across the board is the right default for an auth jar — a cookie
+    # the app's own JavaScript reads is not one it should be signing in with.
+    def cookie(name, value, env, max_age: nil)
+      parts = ["#{name}=#{value}", "path=/", "HttpOnly", "SameSite=Lax"]
+      parts << "secure" if env["rack.url_scheme"] == "https" || env["HTTPS"] == "on"
+      parts << "max-age=#{max_age}" if max_age
+      parts << "expires=#{Time.at(0).httpdate}" if max_age&.zero?
+      parts.join("; ")
+    end
+  end
+end

data/lib/everywhere/auth_token.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "openssl"
+
+module Everywhere
+  # The sealed envelopes the native auth flow passes around: the marker cookie
+  # that says "this browser session is completing a sign-in for the app", and
+  # the handoff token that carries the resulting cookie jar back into the app's
+  # web view.
+  #
+  # Self-contained (encrypt-then-authenticate, expiry inside the payload) rather
+  # than a server-side store: the flow crosses processes — and in a load-balanced
+  # deploy, hosts — between the auth browser and the web view, and a shared
+  # store would be one more thing to configure. AES-256-GCM with the purpose as
+  # associated data, so a marker can never be replayed as a handoff token.
+  module AuthToken
+    CIPHER = "aes-256-gcm"
+    NONCE_BYTES = 12
+    TAG_BYTES = 16
+
+    class MissingSecret < StandardError; end
+
+    class << self
+      # The secret the tokens are keyed from. Set explicitly, or left to be
+      # discovered: the Rails app's secret_key_base, else SECRET_KEY_BASE /
+      # EVERYWHERE_AUTH_SECRET from the environment (Sinatra/Hanami).
+      attr_writer :secret
+
+      def secret
+        @secret ||= discover_secret or raise(MissingSecret, <<~MESSAGE)
+          Native sign-in needs a secret to seal its handoff tokens. Rails apps use
+          secret_key_base automatically; elsewhere set SECRET_KEY_BASE (or
+          EVERYWHERE_AUTH_SECRET) in the environment, or assign
+          Everywhere::AuthToken.secret at boot.
+        MESSAGE
+      end
+
+      def encrypt(payload, purpose:, ttl:)
+        sealed = JSON.generate(payload.merge("exp" => now + ttl))
+        cipher = OpenSSL::Cipher.new(CIPHER).encrypt
+        cipher.key = key
+        nonce = cipher.random_iv
+        cipher.auth_data = purpose.to_s
+        ciphertext = cipher.update(sealed) + cipher.final
+        Base64.urlsafe_encode64(nonce + cipher.auth_tag + ciphertext, padding: false)
+      end
+
+      # The payload, or nil for anything we can't fully vouch for: tampered,
+      # wrong purpose, expired, or (when `once`) already spent. Never raises on
+      # bad input — every one of these arrives from outside.
+      def decrypt(token, purpose:, once: false)
+        raw = Base64.urlsafe_decode64(token.to_s)
+        return nil if raw.bytesize <= NONCE_BYTES + TAG_BYTES
+
+        decipher = OpenSSL::Cipher.new(CIPHER).decrypt
+        decipher.key = key
+        decipher.iv = raw.byteslice(0, NONCE_BYTES)
+        decipher.auth_tag = raw.byteslice(NONCE_BYTES, TAG_BYTES)
+        decipher.auth_data = purpose.to_s
+
+        payload = JSON.parse(decipher.update(raw.byteslice(NONCE_BYTES + TAG_BYTES..)) + decipher.final)
+        return nil unless payload.is_a?(Hash) && payload["exp"].to_i > now
+        return nil if once && !claim(token, payload["exp"].to_i)
+
+        payload
+      rescue ArgumentError, OpenSSL::Cipher::CipherError, JSON::ParserError
+        nil
+      end
+
+      # Test hook — a new secret means a new key.
+      def reset!
+        @secret = nil
+        @key = nil
+        @spent = nil
+      end
+
+      private
+
+      def key
+        @key ||= OpenSSL::Digest::SHA256.digest("ruby_everywhere/auth-token\0#{secret}")
+      end
+
+      def discover_secret
+        if defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application
+          base = ::Rails.application.secret_key_base
+          return base if base && !base.empty?
+        end
+        %w[SECRET_KEY_BASE EVERYWHERE_AUTH_SECRET].each do |name|
+          value = ENV[name]
+          return value if value && !value.empty?
+        end
+        nil
+      end
+
+      # Spend a token, returning false if it was already spent. In-process only:
+      # across workers the ceiling is the token's own (seconds-long) expiry,
+      # which is the guarantee that actually matters — the token never leaves
+      # the device, and a replay would only re-establish the session its owner
+      # already holds.
+      def claim(token, expires_at)
+        digest = OpenSSL::Digest::SHA256.hexdigest(token.to_s)
+        spent_mutex.synchronize do
+          spent.reject! { |_, exp| exp <= now }
+          return false if spent.key?(digest)
+
+          spent[digest] = expires_at
+          true
+        end
+      end
+
+      def spent = @spent ||= {}
+      def spent_mutex = @spent_mutex ||= Mutex.new
+      def now = Time.now.to_i
+    end
+  end
+end