feat(onboarding): honor return_to hint in TikTok OAuth callback (#14569)

When connecting a TikTok 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 TikTok's signed 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.

## What changed
- `Tiktok::IntegrationHelper`: the signed JWT carries an optional
`return_to` claim, added only when present (a request without it is
byte-identical to before); added `tiktok_token_return_to` to read it;
`decode_token` now returns the full payload and `verify_tiktok_token`
derives the account id from it.
- `Tiktok::AuthorizationsController#create` passes `params[:return_to]`
into the token.
- `Tiktok::CallbacksController` redirects to the onboarding inbox-setup
screen when `return_to == 'onboarding'`, before the normal
settings/agents redirect.
- Added the `app_onboarding_inbox_setup` route (shared with the sibling
Gmail/Outlook and Instagram PRs — keep a single copy on merge to avoid a
duplicate route name).

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

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

@@ -3,7 +3,7 @@ class Api::V1::Accounts::Tiktok::AuthorizationsController < Api::V1::Accounts::O
 
   def create
     redirect_url = Tiktok::AuthClient.authorize_url(
-      state: generate_tiktok_token(Current.account.id)
+      state: generate_tiktok_token(Current.account.id, params[:return_to])
     )
 
     if redirect_url

app/controllers/tiktok/callbacks_controller.rb

@@ -20,6 +20,8 @@ class Tiktok::CallbacksController < ApplicationController
   def process_successful_authorization
     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_tiktok_inbox_settings_url(account_id: account_id, inbox_id: inbox.id)
     else
@@ -127,6 +129,10 @@ class Tiktok::CallbacksController < ApplicationController
     @account_id ||= verify_tiktok_token(params[:state])
   end
 
+  def return_to
+    tiktok_token_return_to(params[:state])
+  end
+
   def account
     @account ||= Account.find(account_id)
   end

app/helpers/tiktok/integration_helper.rb

@@ -2,11 +2,12 @@ module Tiktok::IntegrationHelper
   # Generates a signed JWT token for Tiktok 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_tiktok_token(account_id)
+  def generate_tiktok_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 TikTok token: #{e.message}")
     nil
@@ -19,7 +20,14 @@ module Tiktok::IntegrationHelper
   def verify_tiktok_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 Tiktok JWT token, if present.
+  def tiktok_token_return_to(token)
+    return if token.blank? || client_secret.blank?
+
+    decode_token(token, client_secret)&.dig('return_to')
   end
 
   private
@@ -28,18 +36,17 @@ module Tiktok::IntegrationHelper
     @client_secret ||= GlobalConfigService.load('TIKTOK_APP_SECRET', 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
 
   def decode_token(token, secret)
     JWT.decode(token, secret, true, {
                  algorithm: 'HS256',
                  verify_expiration: true
-               }).first['sub']
+               }).first
   rescue StandardError => e
     Rails.logger.error("Unexpected error verifying Tiktok token: #{e.message}")
     nil

config/routes.rb

@@ -29,6 +29,7 @@ Rails.application.routes.draw do
     get '/app/accounts/:account_id/settings/inboxes/:inbox_id', to: 'dashboard#index', as: 'app_instagram_inbox_settings'
     get '/app/accounts/:account_id/settings/inboxes/:inbox_id', to: 'dashboard#index', as: 'app_tiktok_inbox_settings'
     get '/app/accounts/:account_id/settings/inboxes/:inbox_id', to: 'dashboard#index', as: 'app_email_inbox_settings'
+    get '/app/accounts/:account_id/onboarding/inbox-setup', to: 'dashboard#index', as: 'app_onboarding_inbox_setup'
 
     resource :widget, only: [:show]
     namespace :survey do