feat(onboarding): honor return_to hint in Instagram OAuth callback (#14568)

When connecting an Instagram inbox during onboarding, the OAuth flow
used to drop users in inbox settings, breaking onboarding. The OAuth
start endpoint now accepts an optional `return_to=onboarding` hint,
carried tamper-proof inside the signed state (a claim on the Instagram
JWT), and the callback uses it to return the user to the onboarding
inbox-setup screen. Without the hint, behavior is unchanged.

This is the backend half only; the frontend that sends
`return_to=onboarding` ships separately.

Co-authored-by: Muhsin Keloth <muhsinkeramam@gmail.com>

app/controllers/api/v1/accounts/instagram/authorizations_controller.rb

@@ -11,7 +11,7 @@ class Api::V1::Accounts::Instagram::AuthorizationsController < Api::V1::Accounts
         enable_fb_login: '0',
         force_authentication: '1',
         response_type: 'code',
-        state: generate_instagram_token(Current.account.id)
+        state: generate_instagram_token(Current.account.id, params[:return_to])
       }
     )
     if redirect_url

app/controllers/instagram/callbacks_controller.rb

@@ -28,6 +28,8 @@ class Instagram::CallbacksController < ApplicationController
     @long_lived_token_response = exchange_for_long_lived_token(@response.token)
     inbox, already_exists = find_or_create_inbox
 
+    return redirect_to app_onboarding_inbox_setup_url(account_id: account_id) if return_to == 'onboarding'
+
     if already_exists
       redirect_to app_instagram_inbox_settings_url(account_id: account_id, inbox_id: inbox.id)
     else
@@ -149,6 +151,10 @@ class Instagram::CallbacksController < ApplicationController
     verify_instagram_token(params[:state])
   end
 
+  def return_to
+    instagram_token_return_to(params[:state])
+  end
+
   def oauth_code
     params[:code]
   end

app/helpers/instagram/integration_helper.rb

@@ -4,21 +4,21 @@ module Instagram::IntegrationHelper
   # Generates a signed JWT token for Instagram integration
   #
   # @param account_id [Integer] The account ID to encode in the token
+  # @param return_to [String, nil] Optional onboarding return hint
   # @return [String, nil] The encoded JWT token or nil if client secret is missing
-  def generate_instagram_token(account_id)
+  def generate_instagram_token(account_id, return_to = nil)
     return if client_secret.blank?
 
-    JWT.encode(token_payload(account_id), client_secret, 'HS256')
+    JWT.encode(token_payload(account_id, return_to), client_secret, 'HS256')
   rescue StandardError => e
     Rails.logger.error("Failed to generate Instagram token: #{e.message}")
     nil
   end
 
-  def token_payload(account_id)
-    {
-      sub: account_id,
-      iat: Time.current.to_i
-    }
+  def token_payload(account_id, return_to = nil)
+    payload = { sub: account_id, iat: Time.current.to_i }
+    payload[:return_to] = return_to if return_to.present?
+    payload
   end
 
   # Verifies and decodes a Instagram JWT token
@@ -28,7 +28,14 @@ module Instagram::IntegrationHelper
   def verify_instagram_token(token)
     return if token.blank? || client_secret.blank?
 
-    decode_token(token, client_secret)
+    decode_token(token, client_secret)&.dig('sub')
+  end
+
+  # Reads the onboarding return hint from a Instagram JWT token, if present.
+  def instagram_token_return_to(token)
+    return if token.blank? || client_secret.blank?
+
+    decode_token(token, client_secret)&.dig('return_to')
   end
 
   private
@@ -41,7 +48,7 @@ module Instagram::IntegrationHelper
     JWT.decode(token, secret, true, {
                  algorithm: 'HS256',
                  verify_expiration: true
-               }).first['sub']
+               }).first
   rescue StandardError => e
     Rails.logger.error("Unexpected error verifying Instagram token: #{e.message}")
     nil