Adapt internal user v2 token handling to hashed tokens

With `hash_token_secrets` enabled, `token.plaintext_token` is only available at creation or rotation time and cannot be retrieved later. This change ensures secure handling of API tokens in line with best practices for hashed token storage.

- Update `InternalUserAccessTokenService#rotate!` to return `token.plaintext_token` at creation time
- Pass the plaintext token from InternalUserAccessTokensController#create to `app/views/devise/registrations/_v2_api_token.html.erb`
- In `_v2_api_token.html.erb`, render the plaintext token when available and display a warning to users to copy and store the token securely, as it will not be shown again after leaving or refreshing the page.
- Updated all affected Spec files as well.
  - The `context 'when user is not authenticated' do` test has been updated. It now enables CSRF protection, enabling the test to accurately capture the behaviour that will be captured in production.

Author: aaronskiba

app/controllers/api/v2/internal_user_access_tokens_controller.rb

@@ -9,7 +9,7 @@ class InternalUserAccessTokensController < ApplicationController
       # POST "/api/v2/internal_user_access_token"
       def create
         authorize current_user, :internal_user_v2_access_token?
-        @token = Api::V2::InternalUserAccessTokenService.rotate!(current_user)
+        @v2_token = Api::V2::InternalUserAccessTokenService.rotate!(current_user)
         @success = true
         respond_to do |format|
           format.js { render 'users/refresh_token' }

app/services/api/v2/internal_user_access_token_service.rb

@@ -24,24 +24,16 @@ class InternalUserAccessTokenService
       INTERNAL_OAUTH_APP_NAME = Rails.application.config.x.application.internal_oauth_app_name
 
       class << self
-        def for_user(user)
-          Doorkeeper::AccessToken.find_by(
-            application_id: application!.id,
-            resource_owner_id: user.id,
-            scopes: READ_SCOPE,
-            revoked_at: nil
-          )
-        end
-
         def rotate!(user)
           revoke_existing!(user)
 
-          Doorkeeper::AccessToken.create!(
+          token = Doorkeeper::AccessToken.create!(
             application_id: application!.id,
             resource_owner_id: user.id,
             scopes: READ_SCOPE,
             expires_in: nil # Overrides Doorkeeper's `access_token_expires_in`
           )
+          token.plaintext_token
         end
 
         # Used by views (e.g. devise/registrations/_v2_api_token.html.erb) to safely

app/views/devise/registrations/_api_token.html.erb

@@ -1,8 +1,9 @@
 <%# locals: user %>
+<% v2_token ||= nil %>
 
 <div id="api-tokens">
   <%# v2 API token %>
-  <%= render partial: "devise/registrations/v2_api_token", locals: { user: user } %>
+  <%= render partial: "devise/registrations/v2_api_token", locals: { user: user, token: v2_token } %>
 
   <% if user.can_use_api? %>
     <%# v0/v1 API token %>

app/views/devise/registrations/_v2_api_token.html.erb

@@ -6,13 +6,19 @@
   </div>
   <div class="card-body">
     <% if Api::V2::InternalUserAccessTokenService.application_present? %>
-      <% token = Api::V2::InternalUserAccessTokenService.for_user(user) %>
       <div class="form-control mb-3 col-xs-8">
         <%= label_tag(:api_token, _('Access token'), class: 'form-label') %>
         <% if token.present? %>
-          <code><%= token.token %></code>
+          <code><%= token %></code>
+          <div class="alert alert-warning">
+            <%= _( "Please copy this token now and store it somewhere safely." ) %><br>
+            <%= _( "It will disappear after you leave or refresh this page." ) %>
+          </div>
         <% else %>
-          <%= _("Click the button below to generate an API token") %>
+          <%= _( "Click the button below to generate an API token" ) %><br>
+          <div class="alert alert-warning">
+            <%= _("If you previously generated and saved a token, please continue using that token.") %>
+          </div>
         <% end %>
       </div>
 

app/views/users/refresh_token.js.erb

@@ -1,6 +1,8 @@
+// This view is called by both InternalUserAccessTokensController#create (provides @v2_token)
+// and UsersController#refresh_token (does not provide @v2_token).
 var msg = '<%= @success ? _("Successfully regenerated your API token.") : _("Unable to regenerate your API token.") %>';
 
 var context = $('#api-tokens');
-context.html('<%= escape_javascript(render partial: "/devise/registrations/api_token", locals: { user: current_user }) %>');
+context.html('<%= escape_javascript(render partial: "/devise/registrations/api_token", locals: { user: current_user, v2_token: @v2_token }) %>');
 renderNotice(msg);
 toggleSpinner(false);

spec/requests/api/v2/internal_user_access_tokens_controller_spec.rb

@@ -41,11 +41,11 @@ def post_create_token
         end.to change { Doorkeeper::AccessToken.count }.by(1)
       end
 
-      it 'assigns the token' do
+      it 'assigns the plaintext token' do
         post_create_token
 
-        expect(assigns(:token)).to be_a(Doorkeeper::AccessToken)
-        expect(assigns(:token).resource_owner_id).to eq(user.id)
+        expect(assigns(:v2_token)).to be_a(String)
+        expect(assigns(:v2_token)).not_to be_blank
       end
 
       it 'renders the refresh_token template' do

spec/services/api/v2/internal_user_access_token_service_spec.rb

@@ -11,56 +11,46 @@ def create_internal_user_access_token
     create(:oauth_access_token, application: oauth_app, resource_owner_id: user.id, scopes: 'read')
   end
 
-  describe '#for_user' do
-    context 'when a token exists for the user' do
-      let!(:access_token) do
-        create_internal_user_access_token
-      end
-
-      it 'returns the access token' do
-        token = described_class.for_user(user)
-        expect(token).to be_present
-        expect(token.resource_owner_id).to eq(user.id)
-      end
-    end
-
-    context 'when no token exists for the user' do
-      it 'returns nil' do
-        token = described_class.for_user(user)
-        expect(token).to be_nil
-      end
-    end
-  end
-
   describe '#rotate!' do
-    def rotate_token_expectations(new_token, old_token = nil) # rubocop:disable Metrics/AbcSize
-      expect(new_token).to be_persisted
+    def rotate_token_expectations(plaintext_token, old_token = nil) # rubocop:disable Metrics/AbcSize
+      # Doorkeeper hashes token via Digest::SHA256
+      hashed = Digest::SHA256.hexdigest(plaintext_token)
+      new_token = Doorkeeper::AccessToken.find_by!(token: hashed)
+      expect(new_token).to be_present
       expect(new_token.resource_owner_id).to eq(user.id)
       expect(new_token.revoked_at).to be_nil
       expect(new_token.scopes.to_s).to include('read')
-      return unless old_token
-
-      expect(new_token).not_to eq(old_token)
-      expect(old_token.revoked_at).not_to be_nil
+      expect(old_token.revoked_at).not_to be_nil if old_token
     end
 
-    context 'when a token already exists' do
-      let!(:old_token) do
-        create_internal_user_access_token
+    shared_examples 'token rotation' do |has_old_token|
+      it "#{if has_old_token
+              'revokes the old token and creates a new one'
+            else
+              'creates a new token'
+            end}
+      (returns plaintext)" do
+        plaintext_token = nil
+        # Ensure .rotate!(user) creates a new AccessToken db entry for user
+        expect { plaintext_token = described_class.rotate!(user) }
+          .to change { Doorkeeper::AccessToken.where(resource_owner_id: user.id).count }
+          .by(1)
+        if has_old_token
+          old_token.reload
+          rotate_token_expectations(plaintext_token, old_token)
+        else
+          rotate_token_expectations(plaintext_token)
+        end
       end
+    end
 
-      it 'revokes the old token and creates a new one' do
-        new_token = described_class.rotate!(user)
-        old_token.reload
-        rotate_token_expectations(new_token, old_token)
-      end
+    context 'when a token already exists' do
+      let!(:old_token) { create_internal_user_access_token }
+      include_examples 'token rotation', true
     end
 
     context 'when no token exists' do
-      it 'creates a new token' do
-        token = described_class.rotate!(user)
-        rotate_token_expectations(token)
-      end
+      include_examples 'token rotation', false
     end
   end
 

spec/views/devise/registrations/_api_token.html.erb_spec.rb

@@ -6,11 +6,6 @@
   let(:app_name) { Rails.application.config.x.application.internal_oauth_app_name }
   let!(:oauth_app) { create(:oauth_application, name: app_name) }
 
-  before do
-    # Clear memoization between tests
-    Api::V2::InternalUserAccessTokenService.instance_variable_set(:@application, nil)
-  end
-
   context 'When a user has the `use_api` permission' do
     it 'renders both the v2 and legacy API token sections' do
       user = create(:user, :org_admin)

spec/views/devise/registrations/_v2_api_token.html.erb_spec.rb

@@ -6,36 +6,32 @@
   let(:user) { create(:user) }
   let(:app_name) { Rails.application.config.x.application.internal_oauth_app_name }
 
+  def render_token_partial(token: nil)
+    render partial: 'devise/registrations/v2_api_token', locals: { user: user, token: token }
+  end
+
   context 'when the OAuth application exists' do
     let!(:oauth_app) { create(:oauth_application, name: app_name) }
 
-    it 'displays the regenerate button' do
-      render partial: 'devise/registrations/v2_api_token', locals: { user: user }
-
-      expect(rendered).to have_link('Regenerate token',
-                                    href: api_v2_internal_user_access_token_path)
+    it 'displays the regenerate button when no token is present' do
+      render_token_partial(token: nil)
+      expect(rendered).to have_selector('button', text: 'Regenerate token')
     end
 
     context 'when user has a token' do
-      let!(:token) do
-        create(:oauth_access_token,
-               application: oauth_app,
-               resource_owner_id: user.id,
-               scopes: 'read')
-      end
+      let(:plaintext_token) { 'plaintext-token-value' }
 
-      it 'displays the token' do
-        render partial: 'devise/registrations/v2_api_token', locals: { user: user }
-
-        expect(rendered).to have_selector('code', text: token.token)
+      it 'displays the token and disables the regenerate button' do
+        render_token_partial(token: plaintext_token)
+        expect(rendered).to have_selector('code', text: plaintext_token)
         expect(rendered).not_to have_content('Click the button below to generate an API token')
+        expect(rendered).to have_selector('button[disabled]', text: 'Regenerate token')
       end
     end
 
     context 'when user does not have a token' do
       it 'displays the generate message' do
-        render partial: 'devise/registrations/v2_api_token', locals: { user: user }
-
+        render_token_partial(token: nil)
         expect(rendered).to have_content('Click the button below to generate an API token')
         expect(rendered).not_to have_selector('code')
       end
@@ -44,17 +40,15 @@
 
   context 'when the OAuth application does not exist' do
     it 'displays the warning message and helpdesk email link' do
-      render partial: 'devise/registrations/v2_api_token', locals: { user: user }
-
+      render_token_partial(token: nil)
       expect(rendered).to have_selector('.alert-warning')
       expect(rendered).to have_content('V2 API token service is currently unavailable')
       expect(rendered).to have_link(href: "mailto:#{Rails.application.config.x.organisation.helpdesk_email}")
     end
 
     it 'does not display the token or regenerate button' do
-      render partial: 'devise/registrations/v2_api_token', locals: { user: user }
-
-      expect(rendered).not_to have_link('Regenerate token')
+      render_token_partial(token: nil)
+      expect(rendered).not_to have_selector('button', text: 'Regenerate token')
       expect(rendered).not_to have_selector('code')
     end
   end