haveapi 0.27.3 → 0.28.0

data/spec/authentication/token_version_routes_spec.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+module AuthSpecTokenVersionRoutes
+  User = Struct.new(:id, :login)
+
+  class << self
+    def reset!
+      tokens.clear
+    end
+
+    def tokens
+      @tokens ||= {}
+    end
+  end
+
+  class LegacyConfig < HaveAPI::Authentication::Token::Config
+    request do
+      handle do |req, res|
+        if req.input[:user] == 'legacy' && req.input[:password] == 'pass'
+          AuthSpecTokenVersionRoutes.tokens['legacy-token'] = User.new(1, 'legacy')
+          res.token = 'legacy-token'
+          res.valid_to = Time.now + 3600
+          res.complete = true
+          res.ok
+        else
+          res.error = 'invalid legacy credentials'
+          res
+        end
+      end
+    end
+
+    renew do
+      handle { |_req, res| res.ok }
+    end
+
+    revoke do
+      handle { |_req, res| res.ok }
+    end
+
+    def find_user_by_token(_request, token)
+      AuthSpecTokenVersionRoutes.tokens[token]
+    end
+  end
+
+  class StrictConfig < HaveAPI::Authentication::Token::Config
+    request do
+      input do
+        string :mfa_code, required: true
+      end
+
+      handle do |_req, res|
+        res.error = 'strict token issuer reached'
+        res
+      end
+    end
+
+    renew do
+      handle { |_req, res| res.ok }
+    end
+
+    revoke do
+      handle { |_req, res| res.ok }
+    end
+
+    def find_user_by_token(_request, token)
+      AuthSpecTokenVersionRoutes.tokens[token]
+    end
+  end
+
+  LegacyProvider = HaveAPI::Authentication::Token.with_config(LegacyConfig)
+  StrictProvider = HaveAPI::Authentication::Token.with_config(StrictConfig)
+
+  ApiModule = Module.new do
+    def self.define_resource(name, superclass: HaveAPI::Resource, &block)
+      cls = Class.new(superclass)
+      const_set(name, cls)
+      cls.class_exec(&block)
+      cls
+    end
+
+    define_resource(:Secure) do
+      version 2
+
+      define_action(:Ping) do
+        route 'ping'
+        http_method :post
+        auth true
+
+        input(:hash) {}
+        output(:hash) { string :login }
+        authorize { allow }
+
+        def exec
+          { login: current_user.login }
+        end
+      end
+    end
+  end
+end
+
+describe HaveAPI::Authentication::Token do
+  let(:api_instance) do
+    api = HaveAPI::Server.new(AuthSpecTokenVersionRoutes::ApiModule)
+    api.use_version([1, 2])
+    api.default_version = 1
+    api.auth_chain[1] << AuthSpecTokenVersionRoutes::LegacyProvider
+    api.auth_chain[2] << AuthSpecTokenVersionRoutes::StrictProvider
+    api.mount('/')
+    api
+  end
+
+  before do
+    AuthSpecTokenVersionRoutes.reset!
+    api_instance
+  end
+
+  def app
+    api_instance.app
+  end
+
+  it 'does not mount version-specific token issuers on the shared auth path' do
+    call_api(:post, '/_auth/token/tokens', {
+      token: {
+        user: 'legacy',
+        password: 'pass',
+        lifetime: 'permanent',
+        interval: 60
+      }
+    })
+
+    expect(last_response.status).to eq(404)
+    expect(AuthSpecTokenVersionRoutes.tokens).to be_empty
+  end
+
+  it 'routes token requests through the matching API version issuer' do
+    call_api(:post, '/v2/_auth/token/tokens', {
+      token: {
+        user: 'legacy',
+        password: 'pass',
+        lifetime: 'permanent',
+        interval: 60
+      }
+    })
+
+    expect(last_response.status).to eq(400)
+    expect(api_response).to be_failed
+    expect(AuthSpecTokenVersionRoutes.tokens).to be_empty
+
+    call_api(:post, '/v1/_auth/token/tokens', {
+      token: {
+        user: 'legacy',
+        password: 'pass',
+        lifetime: 'permanent',
+        interval: 60
+      }
+    })
+
+    expect(last_response.status).to eq(200)
+    expect(api_response).to be_ok
+    expect(api_response[:token][:token]).to eq('legacy-token')
+  end
+end

data/spec/authorization_spec.rb

@@ -78,6 +78,30 @@ describe HaveAPI::Authorization do
     ).keys).to contain_exactly(:param2)
   end
 
+  it 'normalizes string blacklist entries' do
+    auth = described_class.new do
+      input blacklist: ['param1']
+      output blacklist: ['param1']
+      allow
+    end
+
+    expect(auth.authorized?(nil, {})).to be true
+
+    action = Resource::Index
+    input = action.model_adapter(action.input.layout).input(
+      param1: '123',
+      param2: '456'
+    )
+    output = action.model_adapter(action.output.layout).output(
+      nil,
+      param1: '123',
+      param2: '456'
+    )
+
+    expect(auth.filter_input(action.input.params, input).keys).to contain_exactly(:param2)
+    expect(auth.filter_output(action.output.params, output).keys).to contain_exactly(:param2)
+  end
+
   it 'whitelists output' do
     auth = described_class.new do
       output whitelist: %i[param1]
@@ -115,4 +139,46 @@ describe HaveAPI::Authorization do
       })
     ).keys).to contain_exactly(:param2)
   end
+
+  it 'does not read output parameters excluded by filters' do
+    auth = described_class.new do
+      output whitelist: %i[param1]
+      allow
+    end
+    action = Resource::Index
+    adapter = Class.new do
+      def has_param?(_name)
+        true
+      end
+
+      def [](name)
+        raise 'denied field was read' if name == :param2
+
+        'visible'
+      end
+    end.new
+
+    expect(auth.authorized?(nil, {})).to be true
+    expect(auth.filter_output(action.output.params, adapter)).to eq(param1: 'visible')
+  end
+
+  it 'normalizes string restriction keys' do
+    auth = described_class.new do
+      restrict(**{ 'filter' => true })
+      allow
+    end
+
+    expect(auth.authorized?(nil, {})).to be true
+    expect(auth.restrictions).to eq(filter: true)
+  end
+
+  it 'denies conflicting duplicate restrictions' do
+    auth = described_class.new do
+      restrict filter: 1
+      restrict filter: 2
+      allow
+    end
+
+    expect(auth.authorized?(nil, {})).to be false
+  end
 end

data/spec/documentation/auth_filtering_spec.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# rubocop:disable RSpec/InstanceVariable, RSpec/MultipleDescribes
+
 require 'spec_helper'
 
 module DocAuthFilteringSpec
@@ -9,13 +11,120 @@ module DocAuthFilteringSpec
     protected
 
     def find_user(_request, username, password)
-      return User.new(1, username) if username == 'user' && password == 'pass'
+      return User.new(1, username) if %w[user admin].include?(username) && password == 'pass'
 
       nil
     end
   end
 end
 
+module DocAuthProviderResourceSpec
+  class Provider < HaveAPI::Authentication::Base
+    auth_method :secret_auth
+
+    def resource_module
+      Resources
+    end
+
+    def authenticate(_request)
+      :user
+    end
+  end
+
+  module Resources
+    class HiddenToken < HaveAPI::Resource
+      desc 'Internal authentication resource'
+      auth false
+      version :all
+
+      class Show < HaveAPI::Action
+        route '{hidden_token_id}'
+
+        output(:hash) do
+          string :id
+        end
+
+        authorize { deny }
+      end
+    end
+  end
+end
+
+module CrossVersionDocAuthSpec
+  User = Struct.new(:login)
+
+  class V1Provider < HaveAPI::Authentication::Basic::Provider
+    protected
+
+    def find_user(_request, username, password)
+      User.new(username) if username == 'v1-user' && password == 'pass'
+    end
+  end
+
+  class V2Provider < HaveAPI::Authentication::Basic::Provider
+    protected
+
+    def find_user(_request, _username, _password)
+      nil
+    end
+  end
+
+  ApiModule = Module.new do
+    def self.define_resource(name, superclass: HaveAPI::Resource, &block)
+      cls = Class.new(superclass)
+      const_set(name, cls)
+      cls.class_exec(&block)
+      cls
+    end
+
+    define_resource(:Public) do
+      version 1
+      route 'publics'
+
+      define_action(:Ping) do
+        route 'ping'
+        http_method :get
+        auth true
+
+        output(:hash) do
+          string :msg
+        end
+
+        authorize { |user| user ? allow : deny }
+
+        def exec
+          { msg: 'v1' }
+        end
+      end
+    end
+
+    define_resource(:Secret) do
+      version 2
+      route 'secrets'
+
+      define_action(:Reveal) do
+        route 'reveal'
+        http_method :get
+        auth true
+
+        input(:hash) do
+          string :internal_ticket, required: true
+        end
+
+        output(:hash) do
+          string :secret_material
+        end
+
+        authorize { |user| user ? allow : deny }
+
+        def exec
+          { secret_material: 'v2' }
+        end
+      end
+    end
+  end
+end
+
 describe DocAuthFilteringSpec do
   context 'when viewing documentation' do
     api do
@@ -31,6 +140,13 @@ describe DocAuthFilteringSpec do
           output(:hash) { string :msg }
           authorize { allow }
 
+          # rubocop:disable RSpec/NoExpectationExample
+          example 'admin-only public result' do
+            authorize { |user| user&.login == 'admin' }
+            response({ msg: 'ADMIN_ONLY_RESULT' })
+          end
+          # rubocop:enable RSpec/NoExpectationExample
+
           def exec
             { msg: 'public' }
           end
@@ -48,6 +164,15 @@ describe DocAuthFilteringSpec do
             { msg: 'private' }
           end
         end
+
+        define_resource(:HiddenChild) do
+          desc 'Hidden nested resource'
+          auth false
+
+          define_action(:Index, superclass: HaveAPI::Actions::Default::Index) do
+            authorize { deny }
+          end
+        end
       end
     end
 
@@ -84,6 +209,15 @@ describe DocAuthFilteringSpec do
       expect(actions).to have_key(:private)
     end
 
+    it 'prunes nested resources with no authorized actions or children' do
+      login('user', 'pass')
+      call_api(:options, '/v1/')
+
+      expect(last_response.status).to eq(200)
+      expect(api_response).to be_ok
+      expect(api_response[:resources][:secure][:resources]).not_to have_key(:hidden_child)
+    end
+
     it 'restricts action documentation for private actions' do
       header 'Authorization', nil
       call_api(:options, '/v1/secures/private?method=GET')
@@ -107,5 +241,65 @@ describe DocAuthFilteringSpec do
       expect(api_response).to be_ok
       expect(api_response[:method]).to eq('GET')
     end
+
+    it 'hides examples denied to anonymous users from version docs' do
+      header 'Authorization', nil
+      call_api(:options, '/v1/')
+
+      expect(last_response.status).to eq(200)
+      expect(api_response).to be_ok
+
+      examples = api_response[:resources][:secure][:actions][:public][:examples]
+      expect(examples).to be_empty
+    end
+
+    it 'shows examples allowed to authenticated users in version docs' do
+      login('admin', 'pass')
+      call_api(:options, '/v1/')
+
+      expect(last_response.status).to eq(200)
+      expect(api_response).to be_ok
+
+      examples = api_response[:resources][:secure][:actions][:public][:examples]
+      expect(examples.size).to eq(1)
+      expect(examples.first[:response][:msg]).to eq('ADMIN_ONLY_RESULT')
+    end
   end
 end
+
+describe DocAuthProviderResourceSpec do
+  empty_api
+  use_version 1
+  auth_chain DocAuthProviderResourceSpec::Provider
+
+  it 'prunes provider resources with no authorized actions or children' do
+    call_api(:options, '/v1/')
+
+    expect(last_response.status).to eq(200)
+    expect(api_response).to be_ok
+    expect(api_response[:authentication][:secret_auth][:resources]).to be_empty
+  end
+end
+
+describe CrossVersionDocAuthSpec do
+  before do
+    @api = HaveAPI::Server.new(CrossVersionDocAuthSpec::ApiModule)
+    @api.use_version([1, 2])
+    @api.default_version = 1
+    @api.auth_chain[1] << CrossVersionDocAuthSpec::V1Provider
+    @api.auth_chain[2] << CrossVersionDocAuthSpec::V2Provider
+    @api.mount('/')
+  end
+
+  it 'does not describe versions that reject the supplied credentials' do
+    login('v1-user', 'pass')
+    call_api(:options, '/')
+
+    expect(last_response.status).to eq(200)
+    expect(api_response).to be_ok
+    expect(api_response[:versions]).to have_key(:'1')
+    expect(api_response[:versions]).not_to have_key(:'2')
+  end
+end
+
+# rubocop:enable RSpec/InstanceVariable, RSpec/MultipleDescribes

data/spec/documentation/current_user_html_escaping_spec.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+module CurrentUserHtmlEscapingSpec
+  User = Struct.new(:id, :login)
+
+  class BasicProvider < HaveAPI::Authentication::Basic::Provider
+    protected
+
+    def find_user(_request, username, password)
+      return nil unless password == 'pass'
+
+      User.new(1, username)
+    end
+  end
+end
+
+describe CurrentUserHtmlEscapingSpec do
+  api do
+    define_resource(:Ping) do
+      version 1
+      auth false
+
+      define_action(:Index, superclass: HaveAPI::Actions::Default::Index) do
+        authorize { allow }
+      end
+    end
+  end
+
+  default_version 1
+  auth_chain CurrentUserHtmlEscapingSpec::BasicProvider
+
+  it 'escapes the authenticated login in HTML documentation' do
+    payload = '<script>window.__haveapi_xss = 1</script>'
+
+    login(payload, 'pass')
+    get '/v1/'
+
+    expect(last_response.status).to eq(200)
+    expect(last_response.headers['Content-Type']).to include('text/html')
+    expect(last_response.body).not_to include(payload)
+    expect(last_response.body).to include(
+      '&lt;script&gt;window.__haveapi_xss = 1&lt;/script&gt;'
+    )
+  end
+end

data/spec/documentation/examples_spec.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe HaveAPI::Example do
+  api do
+    define_resource(:Widget) do
+      version 1
+      auth false
+
+      define_action(:BulkImport) do
+        route 'bulk_import'
+        http_method :post
+        authorize { allow }
+
+        input(:hash_list) do
+          string :name
+        end
+
+        output(:hash) do
+          integer :count
+        end
+
+        # rubocop:disable RSpec/NoExpectationExample
+        example 'bulk import' do
+          request([{ name: 'alpha' }])
+          response({ count: 1 })
+        end
+        # rubocop:enable RSpec/NoExpectationExample
+
+        def exec
+          { count: input.size }
+        end
+      end
+
+      define_action(:ProseOnly) do
+        route 'prose_only'
+        http_method :get
+        authorize { allow }
+
+        input(:hash) do
+          string :filter
+        end
+
+        output(:hash) do
+          string :name
+        end
+
+        # rubocop:disable RSpec/NoExpectationExample
+        example 'prose only' do
+          comment 'No request or response body is needed.'
+        end
+        # rubocop:enable RSpec/NoExpectationExample
+
+        def exec
+          { name: 'alpha' }
+        end
+      end
+    end
+  end
+
+  default_version 1
+
+  it 'describes list-shaped request examples' do
+    call_api(:options, '/v1/')
+
+    expect(last_response.status).to eq(200)
+    expect(api_response).to be_ok
+
+    examples = api_response[:resources][:widget][:actions][:bulk_import][:examples]
+    expect(examples.first[:request]).to eq([{ name: 'alpha' }])
+
+    call_api(:options, '/v1/widgets/bulk_import?method=POST')
+
+    expect(last_response.status).to eq(200)
+    expect(api_response).to be_ok
+    expect(api_response[:examples].first[:request]).to eq([{ name: 'alpha' }])
+  end
+
+  it 'describes prose-only examples without filtering missing bodies' do
+    call_api(:options, '/v1/')
+
+    expect(last_response.status).to eq(200)
+    expect(api_response).to be_ok
+
+    examples = api_response[:resources][:widget][:actions][:prose_only][:examples]
+    expect(examples.first[:request]).to be_nil
+    expect(examples.first[:response]).to be_nil
+
+    call_api(:options, '/v1/widgets/prose_only?method=GET')
+
+    expect(last_response.status).to eq(200)
+    expect(api_response).to be_ok
+    expect(api_response[:examples].first[:request]).to be_nil
+    expect(api_response[:examples].first[:response]).to be_nil
+  end
+end

data/spec/documentation/host_html_escaping_spec.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+module HostHtmlEscapingSpec
+end
+
+describe HostHtmlEscapingSpec do
+  api do
+    define_resource(:Widget) do
+      version 1
+      auth false
+
+      define_action(:Index, superclass: HaveAPI::Actions::Default::Index) do
+        authorize { allow }
+      end
+    end
+  end
+
+  default_version 1
+
+  it 'escapes request Host values in HTML docs and generated code examples' do
+    payload = 'evil.test"><script>window.__haveapi_host_xss=1</script>'
+
+    header 'Host', payload
+    get '/v1/'
+
+    expect(last_response.status).to eq(200)
+    expect(last_response.headers['Content-Type']).to include('text/html')
+    expect(last_response.body).not_to include('class="login')
+    expect(last_response.body).not_to include(
+      '<script>window.__haveapi_host_xss=1</script>'
+    )
+    expect(last_response.body).to include(
+      'evil.test&quot;&gt;&lt;script&gt;window.__haveapi_host_xss=1&lt;/script&gt;'
+    )
+    expect(last_response.body).to include(
+      'http://evil.test&quot;&gt;&lt;script&gt;window.__haveapi_host_xss=1&lt;/script&gt;'
+    )
+  end
+end

data/spec/documentation_spec.rb

@@ -27,6 +27,10 @@ describe 'Documentation' do
       define_action(:Update, superclass: HaveAPI::Actions::Default::Update) do
         desc 'Update user'
         authorize { allow }
+
+        input(:hash) do
+          string :otp, validate: 'verified by MFA backend'
+        end
       end
     end
 
@@ -173,10 +177,19 @@ describe 'Documentation' do
     expect(last_response.body).to include('HaveAPI documentation')
   end
 
+  it 'has online index doc page without a sidebar template' do
+    get '/doc/index'
+
+    expect(last_response.status).to eq(200)
+    expect(last_response.headers['Content-Type']).to include('text/html')
+    expect(last_response.body).to include('HaveAPI documentation')
+  end
+
   it 'has online doc for every version' do
     get '/v1/'
     expect(last_response.status).to eq(200)
     expect(last_response.headers['Content-Type']).to include('text/html')
+    expect(last_response.body).to include('verified by MFA backend')
 
     get '/v2/'
     expect(last_response.status).to eq(200)