haveapi 0.31.1 → 0.32.0

data/lib/haveapi/views/version_sidebar/auth_resource_nav.erb

@@ -0,0 +1,19 @@
+<ul>
+  <% sort_hash(resources).each do |resource, info| %>
+    <% resource_path = path + [resource.to_s] %>
+    <li><a data-doc-subsection href="#<%= escape_html(documentation_resource_target(resource_path: resource_path, authentication: authentication_provider)) %>"><%= escape_html(resource_path.join('.')) %></a>
+      <ul>
+        <% sort_hash(info[:actions]).each do |action, action_info| %>
+          <li><a data-doc-subsection href="#<%= escape_html(documentation_resource_target(resource_path: resource_path, action_name: action, authentication: authentication_provider)) %>"><%= escape_html(action.to_s.humanize) %></a>
+            <ul>
+              <% documentation_action_sections(action_info, resource_path: resource_path, action_name: action, authentication: authentication_provider).each do |section| %>
+                <li><a data-doc-subsection href="#<%= escape_html(section[:id]) %>"><%= escape_html(section[:label]) %></a></li>
+              <% end %>
+            </ul>
+          </li>
+        <% end %>
+      </ul>
+      <% unless info[:resources].empty? %><%= erb :'version_sidebar/auth_resource_nav', locals: {resources: info[:resources], path: resource_path, authentication_provider: authentication_provider} %><% end %>
+    </li>
+  <% end %>
+</ul>

data/lib/haveapi/views/version_sidebar/authentication_control.erb

@@ -0,0 +1,26 @@
+<% controls = account[:controls] %>
+<% if controls %>
+<div class="authentication">
+  <% if account[:user] && controls[:signed_in] %>
+    <div class="docs-account-content">
+      <span class="sr-only">Account </span><span class="docs-identity"><%= escape_html(account[:user].login) %></span>
+      <form method="post" action="<%= escape_html(controls[:logout_url]) %>">
+        <input type="hidden" name="csrf" value="<%= escape_html(controls[:csrf_token]) %>">
+        <button type="submit">Sign out</button>
+      </form>
+      <% if controls[:switch_user] %>
+        <form method="post" action="<%= escape_html(controls[:logout_url]) %>">
+          <input type="hidden" name="csrf" value="<%= escape_html(controls[:csrf_token]) %>">
+          <input type="hidden" name="switch_user" value="1">
+          <button type="submit">Switch user</button>
+        </form>
+      <% end %>
+    </div>
+  <% else %>
+    <a class="docs-sign-in" href="<%= escape_html(controls[:login_url]) %>" data-documentation-login aria-label="Sign in" title="Sign in">
+      <svg viewBox="0 0 24 24" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="8" r="4"></circle><path d="M4 21v-2a8 8 0 0 1 16 0v2"></path></svg>
+      <span>Sign in</span>
+    </a>
+  <% end %>
+</div>
+<% end %>

data/lib/haveapi/views/version_sidebar/authentication_status.erb

@@ -0,0 +1,3 @@
+<% controls = account[:controls] %>
+<p class="docs-visibility-note"><%= account[:user] ? 'Showing resources, actions and parameters available to this account.' : 'Showing all resources, actions and parameters.' %></p>
+<% if controls && controls[:message] %><p role="status"><%= escape_html(controls[:message]) %></p><% end %>

data/lib/haveapi/views/version_sidebar/brand.erb

@@ -0,0 +1,31 @@
+<div class="docs-brand">
+  <a href="<%= escape_html(url(root, false)) %>"><%= escape_html(documentation_identity_name) %></a>
+  <% if @v %><small class="docs-api-version">API v<%= escape_html(@v) %></small><% end %>
+  <details data-documentation-menu>
+    <summary aria-label="Documentation settings" title="Documentation settings">
+      <svg viewBox="0 0 24 24" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="2"><path d="m9.5 3-.5 2.1-1.7 1-2.1-.6-2.5 4.3 1.6 1.5v2l-1.6 1.5 2.5 4.3 2.1-.6 1.7 1 .5 2.1h5l.5-2.1 1.7-1 2.1.6 2.5-4.3-1.6-1.5v-2l1.6-1.5-2.5-4.3-2.1.6-1.7-1L14.5 3Z"></path><circle cx="12" cy="12" r="3"></circle></svg>
+    </summary>
+    <div data-documentation-menu-content>
+      <span id="docs-theme-label" class="docs-theme-label">Theme</span>
+      <div class="docs-theme-choices" role="group" aria-labelledby="docs-theme-label">
+        <% {auto: 'Automatic theme', light: 'Light theme', dark: 'Dark theme'}.each do |choice, label| %>
+          <button type="button" data-theme-choice="<%= choice %>" aria-label="<%= label %>" title="<%= label %>" aria-pressed="<%= choice == :auto %>">
+            <svg viewBox="0 0 24 24" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="2">
+              <% if choice == :auto %><circle cx="12" cy="12" r="8"></circle><path d="M12 4a8 8 0 0 0 0 16Z" fill="currentColor"></path>
+              <% elsif choice == :light %><circle cx="12" cy="12" r="4"></circle><path d="M12 2v2m0 16v2M2 12h2m16 0h2M5 5l2 2m10 10 2 2M5 19l2-2M17 7l2-2"></path>
+              <% else %><path d="M20 15.5A8.5 8.5 0 0 1 8.5 4 8.5 8.5 0 1 0 20 15.5Z"></path><% end %>
+            </svg>
+          </button>
+        <% end %>
+      </div>
+      <% if account %>
+        <%= erb :'version_sidebar/authentication_control', locals: {account: account} %>
+      <% elsif (account_url = documentation_neutral_account_url) %>
+        <a class="docs-account-link" href="<%= escape_html(account_url) %>" aria-label="Account" title="Account"><svg viewBox="0 0 24 24" aria-hidden="true" focusable="false" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="8" r="4"></circle><path d="M4 21v-2a8 8 0 0 1 16 0v2"></path></svg><span>Account</span></a>
+      <% end %>
+    </div>
+  </details>
+  <% if account %>
+    <%= erb :'version_sidebar/authentication_status', locals: {account: account} %>
+  <% end %>
+</div>

data/lib/haveapi/views/version_sidebar/resource_nav.erb

@@ -1,21 +1,12 @@
-<li>
-  <a href="#<%= "#{prefix}-#{resource}" %>">.<%= resource.humanize %></a>
-
-  <ul>
-    <% sort_hash(info[:actions]).each do |action, info| %>
-      <li>
-        <a href="#<%= "#{prefix}-#{resource}-#{action}" %>">#<%= action.capitalize %></a>
-      </li>
-    <% end %>
-
-    <% sort_hash(info[:resources]).each do |r, i| %>
-      <%=
-        erb :"version_sidebar/resource_nav", locals: {
-          resource: r,
-          info: i,
-          prefix: "#{prefix}-#{resource}",
-        }
-      %>
-    <% end %>
-  </ul>
+<% resource_path = path + [resource.to_s] %>
+<% key = resource_path.join('.') %>
+<li data-resource-item>
+  <a href="<%= escape_html(documentation_url(resource: key)) %>" data-resource-link="<%= escape_html(key) %>"<% if @documentation_resource && @documentation_resource[:key] == key %> aria-current="page"<% end %>><%= escape_html(key) %></a>
+  <% unless info[:resources].empty? %>
+    <ul>
+      <% sort_hash(info[:resources]).each do |child, child_info| %>
+        <%= erb :'version_sidebar/resource_nav', locals: {resource: child, info: child_info, path: resource_path} %>
+      <% end %>
+    </ul>
+  <% end %>
 </li>

data/lib/haveapi/views/version_sidebar.erb

@@ -1,49 +1,60 @@
-<h1>Authentication</h1>
-<p class="authentication">
-  <% if current_user %>
-      Logged as <%= escape_html(current_user.login) %> [<a class="logout" href="<%= escape_html(logout_url) %>">logout</a>]
-  <% elsif @help[:authentication].any? %>
-      <a class="login btn btn-default" href="<%= escape_html(url("#{root}_login")) %>">Login</a>
-  <% else %>
-      Authentication disabled.
+<%= erb :'version_sidebar/brand', locals: {account: documentation_account_context} %>
+<% if (search_options = documentation_search_form_options(id: 'docs-search-sidebar')) %>
+  <%= erb :'documentation/search_form', locals: search_options %>
+<% end %>
+<nav aria-label="Documentation pages">
+  <ul>
+    <li><a href="<%= escape_html(documentation_url) %>"<% if @documentation_page == 'overview' %> aria-current="page"<% end %>>Overview</a></li>
+    <li>
+      <a href="<%= escape_html(documentation_url(page: 'authentication')) %>"<% if @documentation_page == 'authentication' %> aria-current="page"<% end %>>Authentication</a>
+      <% if @documentation_page == 'authentication' %>
+        <nav aria-label="Authentication methods" data-action-nav><%= erb :'version_sidebar/auth_nav', locals: {methods: @help[:authentication]} %></nav>
+      <% end %>
+    </li>
+    <li><a href="<%= escape_html(documentation_url(page: 'resources')) %>"<% if @documentation_page == 'resources' %> aria-current="page"<% end %> data-resource-directory-link>Resources</a></li>
+  </ul>
+</nav>
+<% if @documentation_resource %>
+  <p data-current-resource><a href="<%= escape_html(documentation_url(resource: @documentation_resource[:key])) %>"><strong><%= escape_html(@documentation_resource[:key]) %></strong></a></p>
+  <nav aria-label="Actions on this resource" data-action-nav>
+    <h2>Actions</h2>
+    <ul class="docs-action-list">
+      <% sort_hash(@documentation_resource[:info][:actions]).each do |action, info| %>
+        <% target = documentation_resource_target(resource_path: @documentation_resource[:path], action_name: action) %>
+        <li data-doc-nav-owner="<%= escape_html(target) %>">
+          <a data-doc-primary href="#<%= escape_html(target) %>"><%= escape_html(action.to_s.humanize) %></a>
+          <ul data-doc-subnav="<%= escape_html(target) %>">
+            <% documentation_action_sections(info, resource_path: @documentation_resource[:path], action_name: action).each do |section| %>
+              <li><a data-doc-subsection href="#<%= escape_html(section[:id]) %>"><%= escape_html(section[:label]) %></a></li>
+            <% end %>
+          </ul>
+        </li>
+      <% end %>
+    </ul>
+  </nav>
+  <% unless @documentation_resource[:info][:resources].empty? %>
+    <nav aria-label="Subresources">
+      <h2>Subresources</h2>
+      <ul>
+        <% sort_hash(@documentation_resource[:info][:resources]).each do |child, _child_info| %>
+          <% child_path = @documentation_resource[:path] + [child.to_s] %>
+          <li><a href="<%= escape_html(documentation_url(resource: child_path)) %>"><%= escape_html(child_path.join('.')) %></a></li>
+        <% end %>
+      </ul>
+    </nav>
   <% end %>
-</p>
-<p>
-  <% if current_user %>
-      Listing only accessible resources, actions and parameters.
-  <% else %>
-      Listing all resources, actions and parameters.
-  <% end %>
-</p>
-
-<h1>Contents</h1>
-<ul class="top-level">
-  <li><a href="#api">API v<%= @v %></a></li>
-  <li>
-    <a href="#auth">Authentication</a>
-    <%= erb :"version_sidebar/auth_nav", locals: {methods: @help[:authentication]} %>
-  </li>
-  <li><a href="#resources">Resources</a></li>
-    <% sort_hash(@help[:resources]).each do |resource, info| %>
-      <%=
-        erb :"version_sidebar/resource_nav", locals: {
-          resource: resource,
-          info: info,
-          prefix: 'root',
-        }
-      %>
-  <% end %>
-</ul>
-
-<h1>Browser</h1>
-<p>
-  Browse this API with <a href="https://github.com/vpsfreecz/haveapi-webui">haveapi-webui</a>:
-</p>
-<p>
-  <a
-    href="https://webui.haveapi.org/v<%= version %>/#<%= urlescape(base_url) %>"
-    class="btn btn-default"
-    target="_blank">
-    Connect
-  </a>
-</p>
+<% end %>
+<div class="docs-preferences">
+  <label>Language <select data-language-select>
+    <% documentation_client_metadata.uniq { |client| client[:language] }.each do |client| %>
+      <option value="<%= escape_html(client[:language]) %>"><%= escape_html(client[:language_label]) %></option>
+    <% end %>
+  </select></label>
+  <label data-variant-control>Client <select data-variant-select>
+    <% documentation_clients.each do |client| %>
+      <option value="<%= escape_html(client.id) %>"><%= escape_html(client.variant || client.language_label) %></option>
+    <% end %>
+  </select></label>
+  <label data-detail-control>Examples <select data-detail-select><option value="simple">Simple</option><option value="thorough">With error handling</option></select></label>
+  <p data-preference-status role="status"></p>
+</div>

data/spec/authentication/basic_spec.rb

@@ -117,21 +117,21 @@ describe HaveAPI::Authentication::Basic::Provider do
     expect(seen_users.last).to be_nil
   end
 
-  it 'returns an authentication error envelope from _login' do
+  it 'redirects the legacy documentation login without an authentication challenge' do
     get '/_login'
 
-    expect(last_response.status).to eq(401)
-    expect(last_response.headers['www-authenticate']).to include('Basic realm=')
-    expect(api_response).to be_failed
-    expect(api_response.message).to eq('This action requires authentication')
+    expect(last_response.status).to eq(303)
+    expect(last_response.headers['location']).to eq('/v1/')
+    expect(last_response.headers['www-authenticate']).to be_nil
+    expect(seen_users).to be_empty
   end
 
-  it 'returns an authentication error envelope from _logout' do
+  it 'redirects the legacy documentation logout without an authentication challenge' do
     get '/_logout'
 
-    expect(last_response.status).to eq(401)
-    expect(last_response.headers['www-authenticate']).to include('Basic realm=')
-    expect(api_response).to be_failed
-    expect(api_response.message).to eq('This action requires authentication')
+    expect(last_response.status).to eq(303)
+    expect(last_response.headers['location']).to eq('/v1/')
+    expect(last_response.headers['www-authenticate']).to be_nil
+    expect(seen_users).to be_empty
   end
 end

data/spec/authentication/oauth2_chain_spec.rb

@@ -0,0 +1,72 @@
+require 'spec_helper'
+
+describe HaveAPI::Authentication::Chain do
+  let(:server) { instance_double(HaveAPI::Server, add_auth_routes: nil) }
+  let(:chain) { described_class.new(server) }
+  let(:request) { Rack::Request.new(Rack::MockRequest.env_for('https://docs.example/v1/?access_token=api-token')) }
+  let(:calls) { [] }
+
+  def provider(name, result: nil, token_validation: true, deny_token: false)
+    recorded = calls
+    Class.new(HaveAPI::Authentication::Base) do
+      auth_method name
+      define_method(:authenticate) do |req|
+        recorded << [:ordinary, @version, req]
+        result
+      end
+      if token_validation
+        define_method(:authenticate_access_token) do |req, token|
+          recorded << [:cookie, @version, req, token]
+          deny if deny_token
+          result
+        end
+      end
+    end
+  end
+
+  it 'validates only the requested version OAuth providers in registration order' do
+    chain[1] << provider(:basic, result: :basic_user)
+    chain[1] << provider(:oauth2)
+    chain[1] << provider(:token, result: :token_user)
+    chain[1] << provider(:oauth2, result: :cookie_user)
+    chain[1] << provider(:oauth2, result: :unused_user)
+    chain[2] << provider(:oauth2, result: :other_version)
+    chain.setup([1, 2])
+
+    expect(chain.authenticate_oauth2_token(1, request, 'cookie-token')).to eq(:cookie_user)
+    expect(calls).to eq([[:cookie, 1, request, 'cookie-token'], [:cookie, 1, request, 'cookie-token']])
+    calls.clear
+    expect(chain.authenticate_oauth2_token(2, request, 'cookie-token')).to eq(:other_version)
+    expect(calls).to eq([[:cookie, 2, request, 'cookie-token']])
+  end
+
+  it 'fails closed for a custom oauth2 provider without explicit token validation' do
+    chain[1] << provider(:oauth2, result: :ordinary_user, token_validation: false)
+    chain[1] << provider(:basic, result: :basic_user)
+    chain.setup([1])
+
+    expect(chain.authenticate_oauth2_token(1, request, 'cookie-token')).to be_nil
+    expect(calls).to be_empty
+    expect(chain.authenticate(1, request)).to eq(:ordinary_user)
+    expect(calls).to eq([[:ordinary, 1, request]])
+  end
+
+  it 'preserves provider deny semantics instead of trying a later OAuth provider' do
+    chain[1] << provider(:oauth2, deny_token: true)
+    chain[1] << provider(:oauth2, result: :later_user)
+    chain.setup([1])
+
+    expect(chain.authenticate_oauth2_token(1, request, 'cookie-token')).to be_nil
+    expect(calls).to eq([[:cookie, 1, request, 'cookie-token']])
+  end
+
+  it 'does not authenticate another version or ordinary provider when OAuth is unavailable' do
+    chain[1] << provider(:basic, result: :basic_user)
+    chain[2] << provider(:oauth2, result: :other_user)
+    chain.setup([1, 2])
+
+    expect(chain.authenticate_oauth2_token(1, request, 'cookie-token')).to be_nil
+    expect(chain.authenticate_oauth2_token(3, request, 'cookie-token')).to be_nil
+    expect(calls).to be_empty
+  end
+end

data/spec/authentication/oauth2_token_validation_spec.rb

@@ -0,0 +1,38 @@
+require 'spec_helper'
+
+describe HaveAPI::Authentication::OAuth2::Provider do
+  let(:server) { instance_double(HaveAPI::Server, allow_header: nil) }
+  let(:provider) { described_class.new(server, 1, HaveAPI::Authentication::OAuth2::Config) }
+  let(:request) do
+    env = Rack::MockRequest.env_for(
+      'https://docs.example/v1/?access_token=query-token',
+      'HTTP_AUTHORIZATION' => 'Bearer api-token', 'HTTP_X_HAVEAPI_OAUTH2_TOKEN' => 'custom-token'
+    )
+    Rack::Request.new(env)
+  end
+
+  it 'validates the supplied token with the original request without extracting or mutating API credentials' do
+    request.params
+    original = request.env.dup
+    user = Object.new
+    allow(provider.config).to receive(:find_user_by_access_token).with(request, 'cookie-token').and_return(user)
+
+    expect(provider.authenticate_access_token(request, 'cookie-token')).to equal(user)
+    expect(provider.config).to have_received(:find_user_by_access_token).once
+    expect(request.env).to eq(original)
+    expect(request.params).to eq('access_token' => 'query-token')
+  end
+
+  it 'retains ordinary multiple-token conflict handling before backend lookup' do
+    allow(provider.config).to receive(:find_user_by_access_token)
+    expect { provider.authenticate(request) }.to raise_error(HaveAPI::Authentication::TokenConflict)
+    expect(provider.config).not_to have_received(:find_user_by_access_token)
+  end
+
+  it 'converts only the existing authentication error into a failed token lookup' do
+    allow(provider.config).to receive(:find_user_by_access_token).and_raise(HaveAPI::AuthenticationError)
+    expect(provider.authenticate_access_token(request, 'cookie-token')).to be_nil
+    allow(provider.config).to receive(:find_user_by_access_token).and_raise(TypeError, 'backend contract error')
+    expect { provider.authenticate_access_token(request, 'cookie-token') }.to raise_error(TypeError, 'backend contract error')
+  end
+end