machina-auth 0.1.8 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6d8d740d4e6998400a56db8fe506ce1155221bb7ff216fedda0c48ced30aa06
-  data.tar.gz: bbaf611e06b06f3f8fdf767203ec2106504ba97d8cc4e548881ca5f6909df611
+  metadata.gz: 60692b69e1db477292fba2a947650c2ac15099a616a05318071860a02a550694
+  data.tar.gz: 3625e766f4645037333365f8771e6363be979de0c484ff086b61ced3b335b84b
 SHA512:
-  metadata.gz: 3ca99f12ea236b7a17a84cadc439aa713344c37b2ba2d9a4f59c9d6938b3a7a92f9994f6e79ace9a52203ef64d8dbf3733978f53d70502e14b164efb2bd013f3
-  data.tar.gz: 0c01bf88a2ae86779fcbb2e73ddf94e3269169cade8ced2c50a308e10bd2f54d099c00d1c07fadcabaa2fe4a2ec258683e1b4285e227ad7b7d869f7ba9b80b31
+  metadata.gz: 10cb1b5e52daf7e76f344bfb8445e2ecca186d5cda9b1693dd376cd7ad4e503306229eabe510879ab72cd10c0a275b5c51ba2d84275758539b5fe1d8ca12b482
+  data.tar.gz: a168a7dd638f5663394dda922ba91582bfef041922325c635deff9d2ce79b7828916f21553ab5357d12a8b88276e6f8c560584898c212a9daaea0a4b560a7b98

data/lib/machina/authorized.rb

@@ -5,9 +5,9 @@ module Machina
   # their organization/workspace context, and granted permissions.
   class Authorized
     attr_reader :user_id, :user_email, :user_name, :avatar_url,
-                :organization_id, :org_name, :org_personal, :org_role,
-                :workspace_id, :workspace_name,
-                :session_id, :expires_at, :type
+                :organization_id, :org_name, :org_slug, :org_personal, :org_role,
+                :workspace_id, :workspace_name, :workspace_slug,
+                :session_id, :expires_at, :type, :integration_name
 
     def initialize(data = {})
       assign_user_attrs(data)
@@ -65,6 +65,7 @@ module Machina
     def assign_org_attrs(data)
       @organization_id = data.dig('organization', 'id')
       @org_name        = data.dig('organization', 'name')
+      @org_slug        = data.dig('organization', 'slug')
       @org_personal    = data.dig('organization', 'personal')
       @org_role        = data.dig('membership', 'policy_name') || data.dig('organization', 'role')
     end
@@ -72,13 +73,15 @@ module Machina
     def assign_workspace_attrs(data)
       @workspace_id   = data.dig('workspace', 'id')
       @workspace_name = data.dig('workspace', 'name')
+      @workspace_slug = data.dig('workspace', 'slug')
     end
 
     def assign_session_attrs(data)
-      @type       = data.dig('session', 'type')&.to_sym
-      @session_id = data.dig('session', 'id') || data['session_id']
-      raw_expires = data.dig('session', 'expires_at') || data['expires_at']
-      @expires_at = raw_expires ? Time.zone.parse(raw_expires) : nil
+      @type             = data.dig('session', 'type')&.to_sym
+      @session_id       = data.dig('session', 'id') || data['session_id']
+      @integration_name = data.dig('session', 'integration_name')
+      raw_expires       = data.dig('session', 'expires_at') || data['expires_at']
+      @expires_at       = raw_expires ? Time.zone.parse(raw_expires) : nil
     end
 
     EMPTY = new.freeze # rubocop:disable Lint/UselessConstantScoping

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/identity_client.rb

@@ -19,8 +19,17 @@ module Machina
       @connection = connection
     end
 
-    def resolve_session(token)
-      post('/internal/v1/sessions/resolve', { token: })
+    # @param token [String] raw session token (ps_) or API key (mk_)
+    # @param workspace_id [String, nil] optional workspace UUID hint for org-scoped API keys
+    # @param workspace_slug [String, nil] optional workspace slug hint (alternative to id)
+    # @param organization_slug [String, nil] optional organization slug; identity service
+    #   rejects with 403 if the value does not match the token's bound organization
+    def resolve_session(token, workspace_id: nil, workspace_slug: nil, organization_slug: nil)
+      payload = { token: }
+      payload[:workspace_id]      = workspace_id      if workspace_id
+      payload[:workspace_slug]    = workspace_slug    if workspace_slug
+      payload[:organization_slug] = organization_slug if organization_slug
+      post('/internal/v1/sessions/resolve', payload)
     end
 
     def revoke_session(token)

data/lib/machina/middleware/authentication/hints.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Machina
+  module Middleware
+    class Authentication
+      # Value object representing the workspace + organization hints supplied
+      # with a resolve request. Read from Rack env or request headers, then
+      # forwarded to the identity service as kwargs.
+      #
+      # Sources, in order:
+      #
+      # 1. `env['machina.workspace_hint']` / `env['machina.organization_hint']`
+      #    — set by the product's routes or a Rack middleware when the URL
+      #    itself scopes to an org/workspace (e.g. `/mcp/:org/:workspace`).
+      # 2. `X-Machina-Workspace-Hint` / `X-Machina-Organization-Hint` request
+      #    headers — fallback for clients that can't influence the URL.
+      #
+      # The values are passed through verbatim to the identity service. The
+      # organization hint is enforced as a match against the token's bound
+      # organization (403 on mismatch).
+      # Slug/UUID disambiguation is cheap: UUIDs match a narrow pattern.
+      # Anything else is treated as a slug.
+      HINT_UUID_RE = /\A[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\z/
+      private_constant :HINT_UUID_RE
+
+      Hints = Data.define(:workspace, :organization) do
+        def self.from(env, request)
+          new(
+            workspace: env['machina.workspace_hint'].presence ||
+              request.headers['X-Machina-Workspace-Hint'].presence,
+            organization: env['machina.organization_hint'].presence ||
+              request.headers['X-Machina-Organization-Hint'].presence,
+          )
+        end
+
+        def empty?
+          workspace.nil? && organization.nil?
+        end
+
+        def to_resolve_kwargs
+          kwargs = {}
+          kwargs[HINT_UUID_RE.match?(workspace) ? :workspace_id : :workspace_slug] = workspace if workspace
+          kwargs[:organization_slug] = organization if organization
+          kwargs
+        end
+
+        def cache_suffix
+          empty? ? '' : ":#{organization}:#{workspace}"
+        end
+      end
+    end
+  end
+end

data/lib/machina/middleware/authentication.rb

@@ -1,44 +1,57 @@
 # frozen_string_literal: true
 
+require_relative 'authentication/hints'
+
 module Machina
   module Middleware
     # Rack middleware that extracts authentication tokens from incoming requests,
     # resolves them against the identity service, and sets Current.authorized.
     class Authentication
+      TRANSIENT_FAILURE = :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
       end
 
       def call(env)
         request = ActionDispatch::Request.new(env)
-        # Skip paths allow the developer to disable the middleware from validating
-        # any token or headers on any matched URL or Path.
         return @app.call(env) if skip_path?(request)
 
         token = extract_token(request)
         return @app.call(env) if token.blank?
 
-        session_data = resolve_session(token)
-
-        # Token present but invalid/expired: clear the stale cache entry and
-        # fall through with nil authorized. API callers get 401 from the
-        # controller; browser users get redirected to login by authenticate!.
-        return handle_expired_token(env, request, token) unless session_data
-
-        Machina::Current.authorized = Machina::Authorized.new(session_data)
-
-        @app.call(env)
+        dispatch_session(env, request, token, Hints.from(env, request))
       ensure
         Machina::Current.reset
       end
 
       private
 
-      # Checks whether the request matches any configured skip path.
-      #
-      # Strings match as path prefixes. Regexes match against both the
-      # request path and the full URL, allowing pattern-based exclusions
-      # on host, path, or any combination.
+      def dispatch_session(env, request, token, hints)
+        session_data = resolve_session(token, hints)
+
+        if session_data.is_a?(Hash)
+          Machina::Current.authorized = Machina::Authorized.new(session_data)
+          return @app.call(env)
+        end
+
+        if transient_failure?(session_data)
+          @app.call(env)
+        else
+          handle_expired_token(env, request, token)
+        end
+      end
+
+      def transient_failure?(result)
+        result == TRANSIENT_FAILURE
+      end
+
+      # Strings match as path prefixes; regexes match path or full URL.
       def skip_path?(request)
         return false if Machina.config.skip_paths.blank?
 
@@ -53,13 +66,9 @@ module Machina
         end
       end
 
-      # Clears the cache entry for the expired token and, when the token
-      # originated from the session cookie, deletes that cookie so the
-      # browser stops sending it on subsequent requests. This prevents a
-      # redirect loop where an expired cookie shadows fresh callback tokens.
+      # 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)
-        Machina.cache.delete(cache_key(token))
-
         status, headers, body = @app.call(env)
         Rack::Utils.delete_cookie_header!(headers, 'machina_session') if request.cookies['machina_session'] == token
         [status, headers, body]
@@ -84,25 +93,32 @@ module Machina
         match && match[1]
       end
 
-      def resolve_session(token)
-        cached = Machina.cache.read(cache_key(token))
-        return cached if cached.present? && !(cached.is_a?(Hash) && cached[:stale])
-
-        fetch_from_identity_service(token)
+      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)
+      rescue Faraday::Error => e
+        # Network-level failures (connection refused, timeout, DNS) are
+        # transient — return stale cached data when available, otherwise
+        # signal transient failure so the caller preserves the cookie.
+        Rails.logger.warn("[machina] Identity service unreachable: #{e.class} — #{e.message}")
+        cached.presence || TRANSIENT_FAILURE
       rescue StandardError
         nil
       end
 
-      def fetch_from_identity_service(token)
-        response = Machina.identity_client.resolve_session(token)
+      def fetch_from_identity_service(token, hints)
+        response = Machina.identity_client.resolve_session(token, **hints.to_resolve_kwargs)
 
         unless response.success?
-          Machina.cache.delete(cache_key(token))
+          Machina.cache.write(cache_key(token, hints), INVALID_SESSION, expires_in: Machina.config.negative_cache_ttl)
           return nil
         end
 
         data = unwrap_payload(response.parsed)
-        Machina.cache.write(cache_key(token), data, expires_in: Machina.config.cache_ttl)
+        Machina.cache.write(cache_key(token, hints), data, expires_in: Machina.config.cache_ttl)
         cache_workspace_ref(data)
         data
       end
@@ -112,25 +128,18 @@ module Machina
       end
 
       def cache_workspace_ref(data)
-        workspace    = data['workspace']
-        organization = data['organization']
-
+        workspace, organization = data.values_at('workspace', 'organization')
         return unless workspace.is_a?(Hash) && organization.is_a?(Hash)
         return unless defined?(Machina::WorkspaceRef) && Machina::WorkspaceRef.table_exists?
 
         ref = Machina::WorkspaceRef.find_or_initialize_by(tenant_ref: workspace['id'])
-
-        ref.name = workspace['name']
-        ref.cached_at = Time.current
-        ref.organization_id = organization['id']
-
-        ref.save!
+        ref.update!(name: workspace['name'], cached_at: Time.current, organization_id: organization['id'])
       rescue StandardError
         nil
       end
 
-      def cache_key(token)
-        "machina:session:#{token}"
+      def cache_key(token, hints)
+        "machina:session:#{token}#{hints.cache_suffix}"
       end
     end
   end

data/lib/machina/test_helpers.rb

@@ -127,7 +127,8 @@ module Machina
       {
         'id' => '00000000-0000-4000-a000-000000001000',
         'type' => 'platform_session',
-        'expires_at' => (Time.now.utc + 86_400).iso8601
+        'expires_at' => (Time.now.utc + 86_400).iso8601,
+        'integration_name' => nil
       }
     end
   end

data/lib/machina/version.rb

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

data/lib/machina/webhook_receiver.rb

@@ -63,7 +63,7 @@ module Machina
         entry = cache.read(key)
         next unless entry.is_a?(Hash)
 
-        cache.write(key, entry.merge(stale: true))
+        cache.write(key, entry.merge('stale' => true))
       end
     end
 

data/spec/contracts/session_resolution_contract_spec.rb

@@ -68,6 +68,26 @@ RSpec.describe 'Session Resolution Contract' do
       end.not_to raise_error
     end
 
+    it 'accepts an optional workspace_id hint' do
+      expect do
+        ConsoleSchema.validate!(
+          { 'token' => 'mk_abc', 'workspace_id' => 'b2c3d4e5-f6a7-8901-bcde-f12345678901' },
+          schema_key,
+          'request.body',
+        )
+      end.not_to raise_error
+    end
+
+    it 'accepts an optional workspace_slug hint' do
+      expect do
+        ConsoleSchema.validate!(
+          { 'token' => 'mk_abc', 'workspace_slug' => 'zar' },
+          schema_key,
+          'request.body',
+        )
+      end.not_to raise_error
+    end
+
     it 'fails when token is missing' do
       expect { ConsoleSchema.validate!({}, schema_key, 'request.body') }.to raise_error(/Schema validation failed/)
     end

data/spec/machina/authorized_spec.rb

@@ -18,6 +18,7 @@ RSpec.describe Machina::Authorized do
     it 'exposes organization attributes' do
       expect(authorized.organization_id).to eq('a1b2c3d4-e5f6-7890-abcd-ef1234567890')
       expect(authorized.org_name).to eq('ZAR')
+      expect(authorized.org_slug).to eq('zar')
       expect(authorized.org_personal).to be(false)
       expect(authorized.org_role).to eq('admin')
     end
@@ -25,6 +26,15 @@ RSpec.describe Machina::Authorized do
     it 'exposes workspace attributes' do
       expect(authorized.workspace_id).to eq('b2c3d4e5-f6a7-8901-bcde-f12345678901')
       expect(authorized.workspace_name).to eq('Primary')
+      expect(authorized.workspace_slug).to eq('primary')
+    end
+
+    it 'returns nil for slugs when missing from payload (older Console)' do
+      data['organization'].delete('slug')
+      data['workspace'].delete('slug')
+      auth = described_class.new(data)
+      expect(auth.org_slug).to be_nil
+      expect(auth.workspace_slug).to be_nil
     end
 
     it 'aliases tenant_ref to workspace_id' do
@@ -36,6 +46,18 @@ RSpec.describe Machina::Authorized do
     end
   end
 
+  describe '#integration_name' do
+    it 'returns nil when not set' do
+      expect(authorized.integration_name).to be_nil
+    end
+
+    it 'returns the value from session data' do
+      data['session']['integration_name'] = 'GitHub Webhooks'
+      auth = described_class.new(data)
+      expect(auth.integration_name).to eq('GitHub Webhooks')
+    end
+  end
+
   describe '#type' do
     it 'returns a symbol' do
       expect(authorized.type).to eq(:platform_session)

data/spec/machina/identity_client_spec.rb

@@ -25,6 +25,29 @@ RSpec.describe Machina::IdentityClient do
     expect(response.parsed).to eq('data' => { 'user' => { 'id' => 'd7e60485-114e-4142-8dc2-c3612f920cc9' } })
   end
 
+  it 'forwards a workspace_id hint when provided' do
+    stubs.post('/internal/v1/sessions/resolve') do |env|
+      expect(JSON.parse(env.body)).to eq(
+        'token' => 'mk_123',
+        'workspace_id' => 'b2c3d4e5-f6a7-8901-bcde-f12345678901',
+      )
+      [200, { 'Content-Type' => 'application/json' }, JSON.generate(data: {})]
+    end
+
+    response = client.resolve_session('mk_123', workspace_id: 'b2c3d4e5-f6a7-8901-bcde-f12345678901')
+    expect(response).to be_success
+  end
+
+  it 'forwards a workspace_slug hint when provided' do
+    stubs.post('/internal/v1/sessions/resolve') do |env|
+      expect(JSON.parse(env.body)).to eq('token' => 'mk_123', 'workspace_slug' => 'zar')
+      [200, { 'Content-Type' => 'application/json' }, JSON.generate(data: {})]
+    end
+
+    response = client.resolve_session('mk_123', workspace_slug: 'zar')
+    expect(response).to be_success
+  end
+
   it 'syncs permissions for a product' do
     product_id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
 

data/spec/machina/middleware/authentication_spec.rb

@@ -42,6 +42,106 @@ RSpec.describe Machina::Middleware::Authentication do
     expect(workspace_ref).to have_attributes(name: 'Primary')
   end
 
+  describe 'workspace hint forwarding' do
+    let(:mock) { MockResponses.session_resolution }
+
+    it 'forwards a slug hint from env to the identity client and keys the cache by it' do
+      expect(identity_client).to receive(:resolve_session)
+        .with('mk_abc', workspace_slug: 'my-org')
+        .and_return(Machina::IdentityClient::Response.new(status: 200, body: mock))
+
+      env = Rack::MockRequest.env_for('/mcp', 'HTTP_AUTHORIZATION' => 'Bearer mk_abc')
+      env['machina.workspace_hint'] = 'my-org'
+
+      status, = middleware.call(env)
+      expect(status).to eq(200)
+      expect(Machina.cache.read('machina:session:mk_abc::my-org')).to be_a(Hash)
+    end
+
+    it 'forwards a uuid hint as workspace_id rather than slug' do
+      uuid = 'b2c3d4e5-f6a7-8901-bcde-f12345678901'
+      expect(identity_client).to receive(:resolve_session)
+        .with('mk_abc', workspace_id: uuid)
+        .and_return(Machina::IdentityClient::Response.new(status: 200, body: mock))
+
+      env = Rack::MockRequest.env_for('/mcp', 'HTTP_AUTHORIZATION' => 'Bearer mk_abc')
+      env['machina.workspace_hint'] = uuid
+
+      status, = middleware.call(env)
+      expect(status).to eq(200)
+    end
+
+    it 'reads the X-Machina-Workspace-Hint header when env is unset' do
+      expect(identity_client).to receive(:resolve_session)
+        .with('mk_abc', workspace_slug: 'zar')
+        .and_return(Machina::IdentityClient::Response.new(status: 200, body: mock))
+
+      env = Rack::MockRequest.env_for('/mcp',
+                                      'HTTP_AUTHORIZATION' => 'Bearer mk_abc',
+                                      'HTTP_X_MACHINA_WORKSPACE_HINT' => 'zar')
+
+      status, = middleware.call(env)
+      expect(status).to eq(200)
+    end
+
+    it 'does not forward a hint when none is set' do
+      expect(identity_client).to receive(:resolve_session)
+        .with('mk_abc')
+        .and_return(Machina::IdentityClient::Response.new(status: 200, body: mock))
+
+      env = Rack::MockRequest.env_for('/mcp', 'HTTP_AUTHORIZATION' => 'Bearer mk_abc')
+
+      status, = middleware.call(env)
+      expect(status).to eq(200)
+    end
+
+    it 'forwards organization_slug from env to the identity client' do
+      expect(identity_client).to receive(:resolve_session)
+        .with('mk_abc', organization_slug: 'zar', workspace_slug: 'default')
+        .and_return(Machina::IdentityClient::Response.new(status: 200, body: mock))
+
+      env = Rack::MockRequest.env_for('/mcp', 'HTTP_AUTHORIZATION' => 'Bearer mk_abc')
+      env['machina.organization_hint'] = 'zar'
+      env['machina.workspace_hint']    = 'default'
+
+      status, = middleware.call(env)
+      expect(status).to eq(200)
+      expect(Machina.cache.read('machina:session:mk_abc:zar:default')).to be_a(Hash)
+    end
+
+    it 'reads the X-Machina-Organization-Hint header when env is unset' do
+      expect(identity_client).to receive(:resolve_session)
+        .with('mk_abc', organization_slug: 'zar')
+        .and_return(Machina::IdentityClient::Response.new(status: 200, body: mock))
+
+      env = Rack::MockRequest.env_for('/mcp',
+                                      'HTTP_AUTHORIZATION' => 'Bearer mk_abc',
+                                      'HTTP_X_MACHINA_ORGANIZATION_HINT' => 'zar')
+
+      status, = middleware.call(env)
+      expect(status).to eq(200)
+    end
+
+    it 'caches hinted and unhinted responses under separate keys' do
+      allow(identity_client).to receive(:resolve_session)
+        .with('mk_abc')
+        .and_return(Machina::IdentityClient::Response.new(status: 200, body: mock))
+      allow(identity_client).to receive(:resolve_session)
+        .with('mk_abc', workspace_slug: 'zar')
+        .and_return(Machina::IdentityClient::Response.new(status: 200, body: mock))
+
+      plain_env = Rack::MockRequest.env_for('/mcp', 'HTTP_AUTHORIZATION' => 'Bearer mk_abc')
+      middleware.call(plain_env)
+
+      hinted_env = Rack::MockRequest.env_for('/mcp', 'HTTP_AUTHORIZATION' => 'Bearer mk_abc')
+      hinted_env['machina.workspace_hint'] = 'zar'
+      middleware.call(hinted_env)
+
+      expect(Machina.cache.read('machina:session:mk_abc')).to be_a(Hash)
+      expect(Machina.cache.read('machina:session:mk_abc::zar')).to be_a(Hash)
+    end
+  end
+
   it 'passes through with nil authorized when resolution fails' do
     allow(identity_client).to receive(:resolve_session).and_return(
       Machina::IdentityClient::Response.new(status: 404, body: '{}'),
@@ -54,10 +154,10 @@ 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)
+    stale_data = MockResponses.session_resolution_minimal['data'].merge('stale' => true)
 
     Machina.cache.write(cache_key, stale_data, expires_in: 5.minutes)
 
@@ -69,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}"
 
@@ -97,7 +198,24 @@ 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
+
+  it 'does not re-hit Console for a rejected token while the negative cache is warm' do
+    token = 'ps_dead_token'
+
+    allow(identity_client).to receive(:resolve_session).with(token).and_return(
+      Machina::IdentityClient::Response.new(status: 404, body: '{}'),
+    )
+
+    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
 
   context 'when a stale cookie coexists with a fresh callback token' do
@@ -180,6 +298,41 @@ RSpec.describe Machina::Middleware::Authentication do
     expect(JSON.parse(body.first)['user_id']).to eq(mock['data']['user']['id'])
   end
 
+  context 'when the identity service is unreachable' do
+    it 'returns stale cached data instead of destroying the session' do
+      token = 'ps_network_blip'
+      cache_key = "machina:session:#{token}"
+      cached_data = MockResponses.session_resolution_minimal['data'].merge('stale' => true)
+
+      Machina.cache.write(cache_key, cached_data, expires_in: 5.minutes)
+
+      allow(identity_client).to receive(:resolve_session).with(token).and_raise(
+        Faraday::ConnectionFailed.new('Connection refused'),
+      )
+
+      env = Rack::MockRequest.env_for('/resource', 'HTTP_AUTHORIZATION' => "Bearer #{token}")
+      status, _headers, body = middleware.call(env)
+
+      expect(status).to eq(200)
+      expect(JSON.parse(body.first)['user_id']).to eq(cached_data['user']['id'])
+    end
+
+    it 'does not delete the cookie on transient network failure' do
+      allow(identity_client).to receive(:resolve_session).with('ps_network_fail').and_raise(
+        Faraday::ConnectionFailed.new('Connection refused'),
+      )
+
+      env = Rack::MockRequest.env_for(
+        '/resource',
+        'HTTP_COOKIE' => 'machina_session=ps_network_fail',
+      )
+
+      _status, headers, _body = middleware.call(env)
+
+      expect(headers['set-cookie']).to be_nil
+    end
+  end
+
   it 'uses the cache on subsequent requests' do
     response = Machina::IdentityClient::Response.new(
       status: 200,

data/spec/machina/test_helpers_spec.rb

@@ -21,6 +21,7 @@ RSpec.describe Machina::TestHelpers do
       expect(authorized.workspace_name).to eq('Test Workspace')
       expect(authorized.session_id).to eq('00000000-0000-4000-a000-000000001000')
       expect(authorized.type).to eq(:platform_session)
+      expect(authorized.integration_name).to be_nil
       expect(authorized.expires_at).to be_a(Time)
       expect(authorized.permissions).to eq([])
     end
@@ -60,6 +61,11 @@ RSpec.describe Machina::TestHelpers do
       expect(authorized.workspace_name).to eq('Staging')
     end
 
+    it 'overrides integration_name via session hash' do
+      authorized = sign_in_as_machina(session: { integration_name: 'Sentry Alerts' })
+      expect(authorized.integration_name).to eq('Sentry Alerts')
+    end
+
     it 'sets permissions' do
       authorized = sign_in_as_machina(permissions: ['reports.view', 'reports.create'])
       expect(authorized.can?('reports.view')).to be(true)

data/spec/machina/webhook_receiver_spec.rb

@@ -36,7 +36,7 @@ RSpec.describe Machina::WebhookReceiver do
       receiver = described_class.new(request, cache:)
 
       expect(receiver.process!).to be(true)
-      expect(cache.read('machina:session:ps_123')).to include(stale: true)
+      expect(cache.read('machina:session:ps_123')).to include('stale' => true)
     end
   end
 

data/spec/support/mock_responses.rb

@@ -13,7 +13,11 @@ module MockResponses
       'data' => {
         'user' => session_user,
         'organization' => session_organization,
-        'workspace' => { 'id' => 'b2c3d4e5-f6a7-8901-bcde-f12345678901', 'name' => 'Primary' },
+        'workspace' => {
+          'id' => 'b2c3d4e5-f6a7-8901-bcde-f12345678901',
+          'name' => 'Primary',
+          'slug' => 'primary'
+        },
         'membership' => { 'id' => 'c3d4e5f6-a7b8-9012-cdef-123456789012', 'policy_name' => 'admin' },
         'permissions' => ['sessions.view'],
         'session' => session_meta
@@ -27,12 +31,12 @@ module MockResponses
   end
 
   def session_organization
-    { 'id' => 'a1b2c3d4-e5f6-7890-abcd-ef1234567890', 'name' => 'ZAR', 'personal' => false }
+    { 'id' => 'a1b2c3d4-e5f6-7890-abcd-ef1234567890', 'name' => 'ZAR', 'slug' => 'zar', 'personal' => false }
   end
 
   def session_meta
     { 'id' => 'd4e5f6a7-b8c9-0123-def0-1234567890ab', 'type' => 'platform_session',
-      'expires_at' => '2026-03-20T12:00:00Z' }
+      'expires_at' => '2026-03-20T12:00:00Z', 'integration_name' => nil }
   end
 
   # A minimal resolution response for cache tests (fewer fields populated).
@@ -42,7 +46,11 @@ module MockResponses
       'data' => {
         'user' => { 'id' => 'd7e60485-114e-4142-8dc2-c3612f920cc9' },
         'organization' => { 'id' => 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' },
-        'workspace' => { 'id' => 'b2c3d4e5-f6a7-8901-bcde-f12345678901', 'name' => 'Primary' },
+        'workspace' => {
+          'id' => 'b2c3d4e5-f6a7-8901-bcde-f12345678901',
+          'name' => 'Primary',
+          'slug' => 'primary'
+        },
         'permissions' => ['sessions.view'],
         'session' => { 'id' => 'd4e5f6a7-b8c9-0123-def0-1234567890ab', 'type' => 'platform_session',
                        'expires_at' => nil }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: machina-auth
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.4.0
 platform: ruby
 authors:
 - ZAR
@@ -152,6 +152,7 @@ files:
 - lib/machina/errors.rb
 - lib/machina/identity_client.rb
 - lib/machina/middleware/authentication.rb
+- lib/machina/middleware/authentication/hints.rb
 - lib/machina/permission_sync.rb
 - lib/machina/tasks/sync.rake
 - lib/machina/test_helpers.rb