machina-auth 0.4.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 60692b69e1db477292fba2a947650c2ac15099a616a05318071860a02a550694
-  data.tar.gz: 3625e766f4645037333365f8771e6363be979de0c484ff086b61ced3b335b84b
+  metadata.gz: 64cd50975d04d89620d0ad73d6be045f93256efc4d34c57a563782167e659dc2
+  data.tar.gz: 3a962c88b3b58a015fb267de869acc17575cf7377df37b1bfe4439c0bbc66eba
 SHA512:
-  metadata.gz: 10cb1b5e52daf7e76f344bfb8445e2ecca186d5cda9b1693dd376cd7ad4e503306229eabe510879ab72cd10c0a275b5c51ba2d84275758539b5fe1d8ca12b482
-  data.tar.gz: a168a7dd638f5663394dda922ba91582bfef041922325c635deff9d2ce79b7828916f21553ab5357d12a8b88276e6f8c560584898c212a9daaea0a4b560a7b98
+  metadata.gz: b8962c63372568bacb6c6afa2ea47a0530999c0299a39117cbeefee5cec676f81fa25eba413aa3f093e26201878446412a4c9a5fac7f5df7604a13f6078876cf
+  data.tar.gz: 5cc1964cc2c24e6f4d3ddd9e45334bd2dec68a59fdeb73c85ccfc604cd4d19c49094ab6decec799c2d71862f88bd37e8310c1e1801d4d0c5d85cbb383f4ef956

data/README.md

@@ -4,7 +4,8 @@ Rails engine that integrates product apps with the Machina Console identity serv
 
 ## What It Provides
 
-- **Authentication middleware** — extracts session tokens from cookies, headers, or params and resolves them against the Console
+- **Authentication middleware** — extracts session tokens from cookies or headers and resolves them against the Console
+- **Auth callback** — the engine serves `GET <mount>/callback`, completing the Console login handshake with CSRF-state verification (see `docs/PRODUCT_CALLBACK_FLOW.md`)
 - **`Machina::Authorized`** — frozen value object with `can?`, `cannot?`, `authorize!`, and permission query methods
 - **`Machina::Current`** — thread-safe current attributes (user, org, workspace, session)
 - **`Machina::ControllerHelpers`** — `require_authorized!` and `authorize!` for controllers

data/app/controllers/machina/callbacks_controller.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Machina
+  # Completes the Console auth handshake. Console redirects here with the
+  # minted session token; the state nonce issued by +authenticate!+ must be
+  # echoed back or the token is rejected (login-CSRF / session fixation).
+  # The engine has no ApplicationController; Base is required for cookies.
+  class CallbacksController < ActionController::Base # rubocop:disable Rails/ApplicationController
+    def show
+      return reject('missing token') if params[:token].blank?
+      return reject('state mismatch') unless valid_state?
+
+      cookies.delete(:machina_state)
+      reset_session
+      store_session_cookie
+      redirect_to safe_return_to
+    end
+
+    private
+
+    def valid_state?
+      expected = cookies.signed[:machina_state]
+      given = params[:state].to_s
+      expected.present? && given.present? && ActiveSupport::SecurityUtils.secure_compare(given, expected)
+    end
+
+    def reject(reason)
+      cookies.delete(:machina_state)
+      Rails.logger.warn("[machina] Auth callback rejected: #{reason}")
+      render plain: 'Invalid authentication callback', status: :unprocessable_content
+    end
+
+    def store_session_cookie
+      cookies[:machina_session] = {
+        value: params[:token],
+        httponly: true,
+        same_site: :lax,
+        secure: Machina.secure_cookies?
+      }
+    end
+
+    # Relative paths only — an absolute or protocol-relative return_to is an
+    # open redirect on a credential-bearing request.
+    def safe_return_to
+      value = params[:return_to].to_s
+      return value if value.start_with?('/') && !value.start_with?('//')
+
+      '/'
+    end
+  end
+end

data/config/routes.rb

@@ -2,4 +2,5 @@
 
 Machina::Engine.routes.draw do
   post 'webhooks', to: 'webhooks#create'
+  get 'callback', to: 'callbacks#show'
 end

data/lib/machina/controller_helpers.rb

@@ -25,7 +25,8 @@ module Machina
       if request.format.json?
         render json: { error: 'unauthorized' }, status: :unauthorized
       else
-        redirect_to Machina.authorize_url(return_to: request.original_url), allow_other_host: true
+        redirect_to Machina.authorize_url(return_to: request.fullpath, state: issue_state),
+                    allow_other_host: true
       end
     end
 
@@ -49,6 +50,21 @@ module Machina
 
     private
 
+    # Mints the single-use CSRF state for the auth handshake. The value rides
+    # on the callback URL through Console; the callback rejects a redirect
+    # whose state does not match this cookie.
+    def issue_state
+      state = SecureRandom.urlsafe_base64(32)
+      cookies.signed[:machina_state] = {
+        value: state,
+        httponly: true,
+        same_site: :lax,
+        secure: Machina.secure_cookies?,
+        expires: 10.minutes
+      }
+      state
+    end
+
     def respond_unauthorized(error)
       if request.format.json?
         render json: { error: 'forbidden', permission: error.message }, status: :forbidden

data/lib/machina/middleware/authentication.rb

@@ -20,7 +20,7 @@ module Machina
 
       def call(env)
         request = ActionDispatch::Request.new(env)
-        return @app.call(env) if skip_path?(request)
+        return @app.call(env) if callback_path?(request) || skip_path?(request)
 
         token = extract_token(request)
         return @app.call(env) if token.blank?
@@ -51,6 +51,16 @@ module Machina
         result == TRANSIENT_FAILURE
       end
 
+      # The callback sets the session cookie itself; resolving a stale cookie
+      # here would answer it with an expired-token deletion that clobbers the
+      # fresh cookie.
+      def callback_path?(request)
+        callback = Machina.config.identity_callback_uri
+        callback.present? && request.path == URI.parse(callback).path
+      rescue URI::InvalidURIError
+        false
+      end
+
       # Strings match as path prefixes; regexes match path or full URL.
       def skip_path?(request)
         return false if Machina.config.skip_paths.blank?
@@ -75,18 +85,11 @@ module Machina
       end
 
       def extract_token(request)
-        extract_param_token(request)
-          || request.cookies['machina_session']
+        request.cookies['machina_session']
           || extract_bearer(request)
           || request.headers['X-Api-Key']
       end
 
-      def extract_param_token(request)
-        request.params['token']
-      rescue ActionDispatch::Http::Parameters::ParseError
-        nil
-      end
-
       def extract_bearer(request)
         auth_header = request.headers['Authorization'].to_s
         match = auth_header.match(/\ABearer\s+(.+)\z/)

data/lib/machina/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Machina
-  VERSION = '0.4.0'
+  VERSION = '1.0.0'
 end

data/lib/machina.rb

@@ -71,11 +71,14 @@ module Machina
     #   present the callback URI config is ignored
     # @param return_to [String, nil] user's intended destination, appended to
     #   +identity_callback_uri+ so the product app can restore it after auth
+    # @param state [String, nil] CSRF nonce appended to the redirect target;
+    #   Console echoes it back and the callback rejects a mismatch
     # @return [String] the full Console authorize URL
     # @raise [ConfigurationError] when +redirect_to+ is omitted and
     #   +identity_callback_uri+ is not configured
-    def authorize_url(redirect_to: nil, return_to: nil)
+    def authorize_url(redirect_to: nil, return_to: nil, state: nil)
       redirect_target = redirect_to.presence || callback_redirect_target(return_to)
+      redirect_target = append_query_param(redirect_target, 'state', state) if state.present?
 
       base = config.identity_service_url.to_s.sub(%r{/\z}, '')
       "#{base}/authorize?redirect_to=#{CGI.escape(redirect_target)}"
@@ -84,9 +87,18 @@ module Machina
     # Convenience wrapper that delegates to {authorize_url} with +return_to+.
     #
     # @param return_to [String] the user's intended destination
+    # @param state [String, nil] CSRF nonce (see {authorize_url})
     # @return [String] the full authorize URL
-    def login_url(return_to:)
-      authorize_url(return_to:)
+    def login_url(return_to:, state: nil)
+      authorize_url(return_to:, state:)
+    end
+
+    # True when session/state cookies must carry the Secure flag. Forced on
+    # outside development/test: +request.ssl?+ is false behind TLS-terminating
+    # load balancers unless the app sets assume_ssl, silently downgrading the
+    # cookie.
+    def secure_cookies?
+      !Rails.env.local?
     end
 
     private
@@ -105,7 +117,12 @@ module Machina
               'identity_callback_uri must be configured to use authorize_url without an explicit redirect_to'
       end
 
-      return_to.present? ? "#{callback}?return_to=#{CGI.escape(return_to)}" : callback
+      return_to.present? ? append_query_param(callback, 'return_to', return_to) : callback
+    end
+
+    def append_query_param(url, key, value)
+      separator = url.include?('?') ? '&' : '?'
+      "#{url}#{separator}#{key}=#{CGI.escape(value)}"
     end
   end
 end

data/spec/machina/authorize_url_spec.rb

@@ -29,6 +29,30 @@ RSpec.describe 'Machina.authorize_url' do
       callback_with_return = 'http://localhost:3000/auth/machina/callback?return_to=http%3A%2F%2Flocalhost%3A3000%2Finquiries%3Fpage%3D2'
       expect(url).to eq("#{base_url}/authorize?redirect_to=#{CGI.escape(callback_with_return)}")
     end
+
+    it 'appends state to the callback URI' do
+      url = Machina.authorize_url(state: 'abc123')
+
+      callback_with_state = 'http://localhost:3000/auth/machina/callback?state=abc123'
+      expect(url).to eq("#{base_url}/authorize?redirect_to=#{CGI.escape(callback_with_state)}")
+    end
+
+    it 'appends state after return_to with an ampersand' do
+      url = Machina.authorize_url(return_to: '/dashboard', state: 'abc123')
+
+      callback = 'http://localhost:3000/auth/machina/callback?return_to=%2Fdashboard&state=abc123'
+      expect(url).to eq("#{base_url}/authorize?redirect_to=#{CGI.escape(callback)}")
+    end
+
+    it 'escapes the state value' do
+      url = Machina.authorize_url(state: 'a+b/c=')
+
+      expect(CGI.unescape(url)).to include("state=#{CGI.escape('a+b/c=')}")
+    end
+
+    it 'omits state when not given' do
+      expect(Machina.authorize_url).not_to include('state')
+    end
   end
 
   context 'when identity_callback_uri is not configured' do

data/spec/machina/controller_helpers_spec.rb

@@ -40,6 +40,26 @@ RSpec.describe Machina::ControllerHelpers, type: :controller do
     expect(CGI.unescape(response.location)).to include('http://localhost:3000/auth/machina/callback?return_to=')
   end
 
+  it 'mints a state cookie and threads the same value through the redirect' do
+    Machina.config.identity_callback_uri = 'http://localhost:3000/auth/machina/callback'
+
+    get :index
+
+    state = controller.send(:cookies).signed[:machina_state]
+    expect(state).to be_present
+    expect(CGI.unescape(response.location)).to include("state=#{CGI.escape(state)}")
+  end
+
+  it 'passes return_to as a relative path so the callback accepts it' do
+    Machina.config.identity_callback_uri = 'http://localhost:3000/auth/machina/callback'
+
+    get :index
+
+    # request.fullpath, not the absolute original_url — safe_return_to in the
+    # callback rejects absolute URLs and would otherwise drop the destination.
+    expect(CGI.unescape(response.location)).to include("return_to=#{CGI.escape('/index')}")
+  end
+
   it 'returns json unauthorized for api-style requests' do
     request.accept = 'application/json'
     get :index, format: :json

data/spec/machina/middleware/authentication_spec.rb

@@ -218,32 +218,50 @@ RSpec.describe Machina::Middleware::Authentication do
     expect(identity_client).to have_received(:resolve_session).with(token).once
   end
 
-  context 'when a stale cookie coexists with a fresh callback token' do
-    let(:stale_token) { 'ps_expired_cookie' }
-    let(:fresh_token) { 'ps_fresh_callback' }
+  describe 'token query param' do
+    it 'never authenticates a request' do
+      allow(identity_client).to receive(:resolve_session)
 
-    before do
-      allow(identity_client).to receive(:resolve_session).with(stale_token).and_return(
-        Machina::IdentityClient::Response.new(status: 404, body: '{}'),
-      )
+      env = Rack::MockRequest.env_for('/resource?token=ps_leaked_in_url')
+      status, _headers, body = middleware.call(env)
 
-      allow(identity_client).to receive(:resolve_session).with(fresh_token).and_return(
-        Machina::IdentityClient::Response.new(status: 200, body: MockResponses.session_resolution),
-      )
+      expect(status).to eq(200)
+      expect(JSON.parse(body.first)['user_id']).to be_nil
+      expect(identity_client).not_to have_received(:resolve_session)
+    end
+  end
+
+  describe 'callback path' do
+    before do
+      Machina.config.identity_callback_uri = 'http://localhost:3000/machina/callback'
     end
 
-    it 'prefers the query param token over the stale cookie' do
+    it 'is skipped entirely, even with a stale session cookie' do
+      allow(identity_client).to receive(:resolve_session)
+
       env = Rack::MockRequest.env_for(
-        '/auth/machina/callback?token=ps_fresh_callback',
+        '/machina/callback?token=ps_fresh&state=abc',
         'HTTP_COOKIE' => 'machina_session=ps_expired_cookie',
       )
 
+      _status, headers, = middleware.call(env)
+
+      # The stale cookie must not be resolved or deleted — the callback
+      # controller overwrites it with the fresh token.
+      expect(identity_client).not_to have_received(:resolve_session)
+      expect(headers['set-cookie']).to be_nil
+    end
+
+    it 'does not skip other paths' do
+      allow(identity_client).to receive(:resolve_session).with('ps_123').and_return(
+        Machina::IdentityClient::Response.new(status: 200, body: MockResponses.session_resolution),
+      )
+
+      env = Rack::MockRequest.env_for('/resource', 'HTTP_COOKIE' => 'machina_session=ps_123')
       status, _headers, body = middleware.call(env)
 
       expect(status).to eq(200)
-      parsed = JSON.parse(body.first)
-      expect(parsed['user_id']).to eq(MockResponses.session_resolution['data']['user']['id'])
-      expect(identity_client).not_to have_received(:resolve_session).with(stale_token)
+      expect(JSON.parse(body.first)['user_id']).to be_present
     end
   end
 

data/spec/requests/machina/callbacks_spec.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require_relative '../../rails_helper'
+
+RSpec.describe Machina::CallbacksController, type: :controller do
+  routes { Machina::Engine.routes }
+
+  let(:state) { 'a-random-state-value' }
+  let(:token) { 'ps_fresh_token' }
+
+  def sign_state_cookie(value)
+    cookies.signed[:machina_state] = value
+  end
+
+  describe 'with a valid state' do
+    before { sign_state_cookie(state) }
+
+    it 'stores the session cookie and redirects to return_to' do
+      get :show, params: { token:, state:, return_to: '/dashboard' }
+
+      expect(response).to redirect_to('/dashboard')
+      expect(response.cookies['machina_session']).to eq(token)
+    end
+
+    it 'sets the session cookie httponly' do
+      get :show, params: { token:, state: }
+
+      set_cookie = response.headers['Set-Cookie'].to_s
+      expect(set_cookie).to match(/machina_session=.*httponly/i)
+    end
+
+    it 'clears the state cookie' do
+      get :show, params: { token:, state: }
+
+      expect(response.cookies).to include('machina_state' => nil)
+    end
+
+    it 'resets the session on credential swap' do
+      session[:stale] = 'pre-login'
+
+      get :show, params: { token:, state: }
+
+      expect(session[:stale]).to be_nil
+    end
+
+    it 'overwrites a stale session cookie' do
+      request.cookies['machina_session'] = 'ps_stale'
+
+      get :show, params: { token:, state: }
+
+      expect(response.cookies['machina_session']).to eq(token)
+    end
+
+    it 'defaults to root when return_to is blank' do
+      get :show, params: { token:, state: }
+
+      expect(response).to redirect_to('/')
+    end
+
+    it 'rejects an absolute return_to' do
+      get :show, params: { token:, state:, return_to: 'https://evil.example.com/' }
+
+      expect(response).to redirect_to('/')
+    end
+
+    it 'rejects a protocol-relative return_to' do
+      get :show, params: { token:, state:, return_to: '//evil.example.com/' }
+
+      expect(response).to redirect_to('/')
+    end
+  end
+
+  describe 'with an invalid state' do
+    it 'rejects a mismatched state' do
+      sign_state_cookie(state)
+
+      get :show, params: { token:, state: 'forged' }
+
+      expect(response).to have_http_status(:unprocessable_content)
+      expect(response.cookies['machina_session']).to be_nil
+    end
+
+    it 'rejects a missing state param' do
+      sign_state_cookie(state)
+
+      get :show, params: { token: }
+
+      expect(response).to have_http_status(:unprocessable_content)
+      expect(response.cookies['machina_session']).to be_nil
+    end
+
+    it 'rejects when no state cookie was issued' do
+      get :show, params: { token:, state: }
+
+      expect(response).to have_http_status(:unprocessable_content)
+      expect(response.cookies['machina_session']).to be_nil
+    end
+
+    it 'rejects a tampered (unsigned) state cookie' do
+      request.cookies['machina_state'] = state
+
+      get :show, params: { token:, state: }
+
+      expect(response).to have_http_status(:unprocessable_content)
+      expect(response.cookies['machina_session']).to be_nil
+    end
+  end
+
+  it 'rejects a blank token' do
+    sign_state_cookie(state)
+
+    get :show, params: { state: }
+
+    expect(response).to have_http_status(:unprocessable_content)
+    expect(response.cookies['machina_session']).to be_nil
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: machina-auth
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 1.0.0
 platform: ruby
 authors:
 - ZAR
@@ -137,6 +137,7 @@ extra_rdoc_files: []
 files:
 - Gemfile
 - README.md
+- app/controllers/machina/callbacks_controller.rb
 - app/controllers/machina/webhooks_controller.rb
 - config/routes.rb
 - lib/generators/machina/install_generator.rb
@@ -188,6 +189,7 @@ files:
 - spec/machina/webhook_receiver_spec.rb
 - spec/machina/workspace_scoped_spec.rb
 - spec/rails_helper.rb
+- spec/requests/machina/callbacks_spec.rb
 - spec/requests/machina/webhooks_spec.rb
 - spec/spec_helper.rb
 - spec/support/console_schema.rb