machina-auth 0.3.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 95a0c331d428907d79a618631f8b39aea1aa20e297090e44229aed0bc93c0324
-  data.tar.gz: 1489dd29fdf00291cb414b57f198d210bd9e1af818d373b4064b7cda6c0f1b66
+  metadata.gz: 64cd50975d04d89620d0ad73d6be045f93256efc4d34c57a563782167e659dc2
+  data.tar.gz: 3a962c88b3b58a015fb267de869acc17575cf7377df37b1bfe4439c0bbc66eba
 SHA512:
-  metadata.gz: '08a671be6f57a8ef5098444165e335e33cfb85e371f7d34d7842699854bab66050f1de191dc203839dc7c4b94dc72a556803699bc08333e453a5552fd0b94007'
-  data.tar.gz: 236485e85bfc0ef18afc0ddde3251b411f8579ff90b1fa870958b403e2175fbfbfce751d9c629d787c9848f709473e7f7f3779843ab6232b100aee27f1acfb83
+  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/configuration.rb

@@ -10,12 +10,14 @@ module Machina
                   :product_slug,
                   :cache_store,
                   :cache_ttl,
+                  :negative_cache_ttl,
                   :manifest,
                   :skip_paths,
                   :identity_callback_uri
 
     def initialize
       @cache_ttl = 5.minutes
+      @negative_cache_ttl = 30.seconds
       @skip_paths = []
     end
   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

@@ -8,7 +8,11 @@ module Machina
     # resolves them against the identity service, and sets Current.authorized.
     class Authentication
       TRANSIENT_FAILURE = :transient_failure
-      private_constant :TRANSIENT_FAILURE
+
+      # Negative-cache marker for a rejected token. A Hash, so it round-trips through any cache coder.
+      INVALID_SESSION = { '__machina_invalid__' => true }.freeze
+
+      private_constant :TRANSIENT_FAILURE, :INVALID_SESSION
 
       def initialize(app)
         @app = app
@@ -16,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?
@@ -39,7 +43,7 @@ module Machina
         if transient_failure?(session_data)
           @app.call(env)
         else
-          handle_expired_token(env, request, token, hints)
+          handle_expired_token(env, request, token)
         end
       end
 
@@ -47,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?
@@ -62,28 +76,20 @@ module Machina
         end
       end
 
-      # Clears the cache and cookie for a token that Console explicitly rejected.
-      def handle_expired_token(env, request, token, hints)
-        Machina.cache.delete(cache_key(token, hints))
-
+      # Clears the cookie for a rejected token. The cache holds the INVALID_SESSION
+      # sentinel (written in fetch_from_identity_service) and must not be cleared here.
+      def handle_expired_token(env, request, token)
         status, headers, body = @app.call(env)
         Rack::Utils.delete_cookie_header!(headers, 'machina_session') if request.cookies['machina_session'] == token
         [status, headers, body]
       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/)
@@ -92,6 +98,7 @@ module Machina
 
       def resolve_session(token, hints)
         cached = Machina.cache.read(cache_key(token, hints))
+        return nil if cached == INVALID_SESSION
         return cached if cached.present? && !(cached.is_a?(Hash) && cached['stale'])
 
         fetch_from_identity_service(token, hints)
@@ -109,7 +116,7 @@ module Machina
         response = Machina.identity_client.resolve_session(token, **hints.to_resolve_kwargs)
 
         unless response.success?
-          Machina.cache.delete(cache_key(token, hints))
+          Machina.cache.write(cache_key(token, hints), INVALID_SESSION, expires_in: Machina.config.negative_cache_ttl)
           return nil
         end
 

data/lib/machina/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Machina
-  VERSION = '0.3.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

@@ -154,7 +154,7 @@ RSpec.describe Machina::Middleware::Authentication do
     expect(JSON.parse(body.first)).to eq('user_id' => nil, 'permissions' => nil)
   end
 
-  it 'evicts cached session and passes through when Console returns non-200 on stale re-fetch' do
+  it 'negative-caches the rejection and passes through when Console returns non-200 on stale re-fetch' do
     token = 'ps_stale_token'
     cache_key = "machina:session:#{token}"
     stale_data = MockResponses.session_resolution_minimal['data'].merge('stale' => true)
@@ -169,10 +169,11 @@ RSpec.describe Machina::Middleware::Authentication do
     status, = middleware.call(env)
 
     expect(status).to eq(200)
-    expect(Machina.cache.read(cache_key)).to be_nil
+    # The stale session is replaced by the short-lived negative sentinel, not deleted.
+    expect(Machina.cache.read(cache_key)).to eq('__machina_invalid__' => true)
   end
 
-  it 'evicts cached session when Console returns non-200 after cache expires' do
+  it 'negative-caches the rejection when Console returns non-200 after cache expires' do
     token = 'ps_expired_cache'
     cache_key = "machina:session:#{token}"
 
@@ -197,35 +198,70 @@ RSpec.describe Machina::Middleware::Authentication do
     status, = middleware.call(env)
 
     expect(status).to eq(200)
-    expect(Machina.cache.read(cache_key)).to be_nil
+    expect(Machina.cache.read(cache_key)).to eq('__machina_invalid__' => true)
   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' }
+  it 'does not re-hit Console for a rejected token while the negative cache is warm' do
+    token = 'ps_dead_token'
 
-    before do
-      allow(identity_client).to receive(:resolve_session).with(stale_token).and_return(
-        Machina::IdentityClient::Response.new(status: 404, body: '{}'),
-      )
+    allow(identity_client).to receive(:resolve_session).with(token).and_return(
+      Machina::IdentityClient::Response.new(status: 404, body: '{}'),
+    )
 
-      allow(identity_client).to receive(:resolve_session).with(fresh_token).and_return(
-        Machina::IdentityClient::Response.new(status: 200, body: MockResponses.session_resolution),
-      )
+    3.times do
+      env = Rack::MockRequest.env_for('/resource', 'HTTP_AUTHORIZATION' => "Bearer #{token}")
+      status, = middleware.call(env)
+      expect(status).to eq(200)
+    end
+
+    # Without negative caching this would be 3 calls; the sentinel absorbs the retries.
+    expect(identity_client).to have_received(:resolve_session).with(token).once
+  end
+
+  describe 'token query param' do
+    it 'never authenticates a request' do
+      allow(identity_client).to receive(:resolve_session)
+
+      env = Rack::MockRequest.env_for('/resource?token=ps_leaked_in_url')
+      status, _headers, body = middleware.call(env)
+
+      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.3.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