shopify_app 22.5.2 → 23.0.0

data/docs/shopify_app/sessions.md

@@ -23,6 +23,7 @@ Sessions are used to make contextual API calls for either a shop (offline sessio
   - [Access scopes](#access-scopes)
     - [`ShopifyApp::ShopSessionStorageWithScopes`](#shopifyappshopsessionstoragewithscopes)
     - [`ShopifyApp::UserSessionStorageWithScopes`](#shopifyappusersessionstoragewithscopes)
+  - [Migrating to Expiring Offline Access Tokens](#migrating-to-expiring-offline-access-tokens)
   - [Migrating from shop-based to user-based token strategy](#migrating-from-shop-based-to-user-based-token-strategy)
   - [Migrating from `ShopifyApi::Auth::SessionStorage` to `ShopifyApp::SessionStorage`](#migrating-from-shopifyapiauthsessionstorage-to-shopifyappsessionstorage)
 
@@ -129,11 +130,11 @@ These methods are already implemented as a part of the `User` and `Shop` models
 Simply include these concerns if you want to use the implementation, and overwrite methods for custom implementation
 
 - `Shop` storage
-  - [ShopSessionStorageWithScopes](https://github.com/Shopify/shopify_app/blob/main/lib/shopify_app/session/shop_session_storage_with_scopes.rb)
+  - [ShopSessionStorageWithScopes](https://github.com/Shopify/shopify_app/blob/main/lib/shopify_app/session/shop_session_storage_with_scopes.rb) (Deprecated in 23.0.0)
   - [ShopSessionStorage](https://github.com/Shopify/shopify_app/blob/main/lib/shopify_app/session/shop_session_storage.rb)
 
 - `User` storage
-  - [UserSessionStorageWithScopes](https://github.com/Shopify/shopify_app/blob/main/lib/shopify_app/session/user_session_storage_with_scopes.rb)
+  - [UserSessionStorageWithScopes](https://github.com/Shopify/shopify_app/blob/main/lib/shopify_app/session/user_session_storage_with_scopes.rb) (Deprecated in 23.0.0)
   - [UserSessionStorage](https://github.com/Shopify/shopify_app/blob/main/lib/shopify_app/session/user_session_storage.rb)
 
 ### Loading Sessions
@@ -206,6 +207,18 @@ user.with_shopify_session do
 end
 ```
 
+**Automatic Token Refresh for Shop Sessions:**
+
+When using `Shop` models with [expiring offline access tokens](#migrating-to-expiring-offline-access-tokens) configured, `with_shopify_session` will automatically refresh expired tokens before executing the block. This ensures your API calls always use valid credentials without manual intervention.
+
+To disable automatic refresh, pass `auto_refresh: false`:
+
+```ruby
+shop.with_shopify_session(auto_refresh: false) do
+  # Token will NOT be refreshed even if expired
+end
+```
+
 #### Re-fetching an access token when API returns Unauthorized
 
 When using `ShopifyApp::EnsureHasSession` and the `new_embedded_auth_strategy` configuration, any **unhandled** Unauthorized `ShopifyAPI::Errors::HttpResponseError` will cause the app to perform token exchange to fetch a new access token from Shopify and the action to be executed again. This will update and store the new access token to the current session instance.
@@ -300,39 +313,153 @@ class MyController < ApplicationController
 end
 ```
 
-## Access scopes
-If you want to customize how access scopes are stored for shops and users, you can implement the `access_scopes` getters and setters in the models that include `ShopifyApp::ShopSessionStorageWithScopes` and `ShopifyApp::UserSessionStorageWithScopes` as shown:
+## Expiry date
+When the configuration flag `check_session_expiry_date` is set to true, the session expiry date will be checked to trigger a re-auth and get a fresh token when it is expired.
+This requires the `ShopifyAPI::Auth::Session` `expires` attribute to be stored.
+
+**Online access tokens (User sessions):**
+- When the `User` model includes the `UserSessionStorage` concern, a DB migration can be generated with `rails generate shopify_app:user_model --skip` to add the `expires_at` attribute to the model
+- Online access tokens cannot be refreshed, so when the token is expired, the user must go through the OAuth flow again to get a new token
+
+**Offline access tokens (Shop sessions):**
+- Offline access tokens can optionally be configured to expire and support automatic refresh. See [Migrating to Expiring Offline Access Tokens](#migrating-to-expiring-offline-access-tokens) for detailed setup instructions
+
+## Migrating to Expiring Offline Access Tokens
+
+You can opt-in to expiring offline access tokens for enhanced security. When enabled, Shopify will issue offline access tokens with an expiration date and a refresh token. `ShopSessionStorage` will then automatically refresh expired tokens when using `with_shopify_session`.
+
+**1. Database Migration:**
+
+Run the shop model generator (use `--skip` to avoid regenerating the Shop model if it already exists):
+
+```bash
+rails generate shopify_app:shop_model --skip
+```
+
+The generator will prompt you to create a migration that adds the `expires_at`, `refresh_token`, and `refresh_token_expires_at` columns. Alternatively, you can create the migration manually:
+
+```ruby
+class AddShopAccessTokenExpiryColumns < ActiveRecord::Migration[7.0]
+  def change
+    add_column :shops, :expires_at, :datetime
+    add_column :shops, :refresh_token, :string
+    add_column :shops, :refresh_token_expires_at, :datetime
+  end
+end
+```
+
+**2. Update Model Concern:**
+
+If your Shop model is using the deprecated `ShopSessionStorageWithScopes` concern, update it to use `ShopSessionStorage`:
 
-### `ShopifyApp::ShopSessionStorageWithScopes`
 ```ruby
+# app/models/shop.rb
 class Shop < ActiveRecord::Base
-  include ShopifyApp::ShopSessionStorageWithScopes
+  include ShopifyApp::ShopSessionStorage  # Change from ShopSessionStorageWithScopes
+end
+```
 
-  def access_scopes=(scopes)
-    # Store access scopes
-  end
-  def access_scopes
-    # Find access scopes
-  end
+`ShopSessionStorage` now automatically handles `access_scopes`, `expires_at`, `refresh_token`, and `refresh_token_expires_at` - no additional concerns needed.
+
+**3. Configuration:**
+
+```ruby
+# config/initializers/shopify_app.rb
+ShopifyApp.configure do |config|
+  # ... other configuration
+
+  # Enable automatic reauthentication when session is expired
+  config.check_session_expiry_date = true
 end
+
+# For ShopifyAPI Context - enable requesting expiring offline tokens
+ShopifyAPI::Context.setup(
+  # ... other configuration
+  expiring_offline_access_tokens: true, # Opt-in to start requesting expiring offline tokens
+)
 ```
 
-### `ShopifyApp::UserSessionStorageWithScopes`
+**4. Refreshing Expired Tokens:**
+
+With the configuration enabled, expired tokens are automatically handled differently based on the flow:
+
+**For user-facing requests (OAuth/Token Exchange flow):**
+When `check_session_expiry_date` is enabled, expired sessions trigger automatic re-authentication through the OAuth flow. This happens transparently when using controller concerns like `EnsureHasSession`.
+
+**For background jobs and non-user interactions:**
+Tokens are automatically refreshed when using `with_shopify_session` from `ShopSessionStorage`:
+
 ```ruby
-class User < ActiveRecord::Base
-  include ShopifyApp::UserSessionStorageWithScopes
+shop = Shop.find_by(shopify_domain: "example.myshopify.com")
 
-  def access_scopes=(scopes)
-    # Store access scopes
-  end
-  def access_scopes
-    # Find access scopes
+# Automatic refresh (default behavior)
+shop.with_shopify_session do
+  # If the token is expired, it will be automatically refreshed before making API calls
+end
+
+# Disable automatic refresh if needed
+shop.with_shopify_session(auto_refresh: false) do
+  # Token will NOT be refreshed even if expired
+end
+
+# Manual refresh
+begin
+  shop.refresh_token_if_expired!
+rescue ShopifyApp::RefreshTokenExpiredError
+  # Handle case where refresh token itself has expired
+  # App needs to go through OAuth flow again
+end
+```
+
+**Error Handling:**
+- `ShopifyApp::RefreshTokenExpiredError` is raised when the refresh token itself is expired
+- When this happens, the user must interact with the app to go through the OAuth flow again to get new tokens
+- The refresh process uses database row-level locking to prevent race conditions from concurrent requests
+
+**5. Migrating Existing Shop Installations:**
+
+⚠️ **Important:** When you enable `offline_access_token_expires: true`, only **new shop installations** will automatically receive expiring tokens during the OAuth flow. Existing shop installations with non-expiring tokens will continue using their current tokens until manually migrated.
+
+To migrate existing shops to expiring tokens, use the `ShopifyAPI::Auth::TokenExchange.migrate_to_expiring_token` method. Here's an example background job to migrate all existing shops:
+
+```ruby
+# app/jobs/migrate_shops_to_expiring_tokens_job.rb
+class MigrateShopsToExpiringTokensJob < ActiveJob::Base
+  queue_as :default
+
+  def perform
+    # Find shops that haven't been migrated yet (no refresh_token or expires_at)
+    shops_to_migrate = Shop.where(expires_at: nil, refresh_token: nil, refresh_token_expires_at: nil)
+
+    shops_to_migrate.find_each do |shop|
+      begin
+        # Migrate to expiring token
+        new_session = ShopifyAPI::Auth::TokenExchange.migrate_to_expiring_token(
+          shop: shop.shopify_domain,
+          non_expiring_offline_token: shop.shopify_token
+        )
+
+        # Store the new session with expiring token and refresh token
+        Shop.store(new_session)
+
+        Rails.logger.info("Successfully migrated #{shop.shopify_domain} to expiring token")
+      rescue ShopifyAPI::Errors::HttpResponseError => e
+        # Handle migration errors (e.g., shop uninstalled, network issues)
+        Rails.logger.error("Failed to migrate #{shop.shopify_domain}: #{e.message}")
+      rescue => e
+        Rails.logger.error("Unexpected error migrating #{shop.shopify_domain}: #{e.message}")
+      end
+    end
   end
 end
 ```
 
-## Expiry date
-When the configuration flag `check_session_expiry_date` is set to true, the user session expiry date will be checked to trigger a re-auth and get a fresh user token when it is expired. This requires the `ShopifyAPI::Auth::Session` `expires` attribute to be stored. When the `User` model includes the `UserSessionStorageWithScopes` concern, a DB migration can be generated with `rails generate shopify_app:user_model --skip` to add the `expires_at` attribute to the model.
+**Migration notes:**
+- This is a **one-time, irreversible operation** per shop
+- The shop must have the app installed and have a valid access token
+- After migration, the shop's offline token will have an expiration date and a refresh token
+
+**Note:** If you choose not to enable expiring offline tokens, the `expires_at`, `refresh_token`, and `refresh_token_expires_at` columns will remain `NULL` and no automatic refresh will occur. Refresh tokens are only available for offline (shop) access tokens. Online (user) access tokens do not support refresh and must be re-authorized through OAuth when expired.
 
 ## Migrating from shop-based to user-based token strategy
 

data/lib/generators/shopify_app/add_app_uninstalled_job/templates/app_uninstalled_job.rb.tt

@@ -1,8 +1,8 @@
 class AppUninstalledJob < ActiveJob::Base
-  extend ShopifyAPI::Webhooks::Handler
+  include ShopifyAPI::Webhooks::WebhookHandler
 
   class << self
-    def handle(topic:, shop:, body:)
+    def handle(topic:, shop:, body:, webhook_id:, api_version:)
       perform_later(topic: topic, shop_domain: shop, webhook: body)
     end
   end

data/lib/generators/shopify_app/add_privacy_jobs/templates/customers_data_request_job.rb.tt

@@ -1,8 +1,8 @@
 class CustomersDataRequestJob < ActiveJob::Base
-  extend ShopifyAPI::Webhooks::Handler
+  include ShopifyAPI::Webhooks::WebhookHandler
 
   class << self
-    def handle(topic:, shop:, body:)
+    def handle(topic:, shop:, body:, webhook_id:, api_version:)
       perform_later(topic: topic, shop_domain: shop, webhook: body)
     end
   end

data/lib/generators/shopify_app/add_privacy_jobs/templates/customers_redact_job.rb.tt

@@ -1,8 +1,8 @@
 class CustomersRedactJob < ActiveJob::Base
-  extend ShopifyAPI::Webhooks::Handler
+  include ShopifyAPI::Webhooks::WebhookHandler
 
   class << self
-    def handle(topic:, shop:, body:)
+    def handle(topic:, shop:, body:, webhook_id:, api_version:)
       perform_later(topic: topic, shop_domain: shop, webhook: body)
     end
   end

data/lib/generators/shopify_app/add_privacy_jobs/templates/shop_redact_job.rb.tt

@@ -1,8 +1,8 @@
 class ShopRedactJob < ActiveJob::Base
-  extend ShopifyAPI::Webhooks::Handler
+  include ShopifyAPI::Webhooks::WebhookHandler
 
   class << self
-    def handle(topic:, shop:, body:)
+    def handle(topic:, shop:, body:, webhook_id:, api_version:)
       perform_later(topic: topic, shop_domain: shop, webhook: body)
     end
   end

data/lib/generators/shopify_app/add_webhook/templates/webhook_job.rb.tt

@@ -1,8 +1,8 @@
 class <%= @job_class_name %> < ActiveJob::Base
-  extend ShopifyAPI::Webhooks::Handler
+  include ShopifyAPI::Webhooks::WebhookHandler
 
   class << self
-    def handle(topic:, shop:, body:)
+    def handle(topic:, shop:, body:, webhook_id:, api_version:)
       perform_later(topic: topic, shop_domain: shop, webhook: body)
     end
   end

data/lib/generators/shopify_app/install/install_generator.rb

@@ -19,7 +19,7 @@ module ShopifyApp
       def create_shopify_app_initializer
         @application_name = format_array_argument(options["application_name"])
         @scope = format_array_argument(options["scope"])
-        @api_version = options["api_version"] || ShopifyAPI::LATEST_SUPPORTED_ADMIN_VERSION
+        @api_version = options["api_version"] || "2025-10"
 
         template("shopify_app.rb", "config/initializers/shopify_app.rb")
       end

data/lib/generators/shopify_app/shop_model/shop_model_generator.rb

@@ -40,6 +40,24 @@ module ShopifyApp
         end
       end
 
+      def create_shop_with_token_refresh_migration
+        token_refresh_prompt = <<~PROMPT
+          To support expiring offline access token with refresh, your Shop model needs to store \
+          token expiration dates and refresh tokens.
+
+          The following migration will add `expires_at`, `refresh_token`, and \
+          `refresh_token_expires_at` columns to the Shop model. \
+          Do you want to include this migration? [y/n]
+        PROMPT
+
+        if new_shopify_cli_app? || Rails.env.test? || yes?(token_refresh_prompt)
+          migration_template(
+            "db/migrate/add_shop_access_token_expiry_columns.erb",
+            "db/migrate/add_shop_access_token_expiry_columns.rb",
+          )
+        end
+      end
+
       def update_shopify_app_initializer
         gsub_file("config/initializers/shopify_app.rb", "ShopifyApp::InMemoryShopSessionStore", "Shop")
       end

data/lib/generators/shopify_app/shop_model/templates/db/migrate/add_shop_access_token_expiry_columns.erb

@@ -0,0 +1,7 @@
+class AddShopAccessTokenExpiryColumns < ActiveRecord::Migration[<%= rails_migration_version %>]
+  def change
+    add_column :shops, :expires_at, :datetime
+    add_column :shops, :refresh_token, :string
+    add_column :shops, :refresh_token_expires_at, :datetime
+  end
+end

data/lib/generators/shopify_app/shop_model/templates/shop.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 class Shop < ActiveRecord::Base
-  include ShopifyApp::ShopSessionStorageWithScopes
+  include ShopifyApp::ShopSessionStorage
 
   def api_version
     ShopifyApp.configuration.api_version

data/lib/generators/shopify_app/user_model/templates/user.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 class User < ActiveRecord::Base
-  include ShopifyApp::UserSessionStorageWithScopes
+  include ShopifyApp::UserSessionStorage
 
   def api_version
     ShopifyApp.configuration.api_version

data/lib/shopify_app/auth/post_authenticate_tasks.rb

@@ -10,6 +10,7 @@ module ShopifyApp
           session_for_shop = session.online? ? shop_session(session) : session
 
           install_webhooks(session_for_shop)
+          install_scripttags(session_for_shop)
 
           perform_after_authenticate_job(session)
         end
@@ -27,6 +28,13 @@ module ShopifyApp
           WebhooksManager.queue(session.shop, session.access_token)
         end
 
+        def install_scripttags(session)
+          ShopifyApp::Logger.debug("PostAuthenticateTasks: Installing scripttags")
+          return unless ShopifyApp.configuration.has_script_tags?
+
+          ScriptTagsManager.queue(session.shop, session.access_token, ShopifyApp.configuration.script_tags)
+        end
+
         def perform_after_authenticate_job(session)
           ShopifyApp::Logger.debug("PostAuthenticateTasks: Performing after_authenticate_job")
           config = ShopifyApp.configuration.after_authenticate_job

data/lib/shopify_app/auth/token_exchange.rb

@@ -60,6 +60,13 @@ module ShopifyApp
       rescue ActiveRecord::RecordNotUnique
         Logger.debug("Session not stored due to concurrent token exchange calls")
         session
+      rescue ActiveRecord::RecordInvalid => e
+        if e.message.include?("has already been taken")
+          Logger.debug("Session not stored due to concurrent token exchange calls")
+          session
+        else
+          raise
+        end
       rescue => error
         Logger.error("An error occurred during the token exchange: [#{error.class}] #{error.message}")
         raise

data/lib/shopify_app/configuration.rb

@@ -15,7 +15,7 @@ module ShopifyApp
     attr_accessor :embedded_app
     alias_method  :embedded_app?, :embedded_app
     attr_accessor :webhooks
-    attr_accessor :scripttags
+    attr_accessor :script_tags
     attr_accessor :after_authenticate_job
     attr_accessor :api_version
 
@@ -33,7 +33,7 @@ module ShopifyApp
     attr_accessor :custom_post_authenticate_tasks
 
     # customise ActiveJob queue names
-    attr_accessor :scripttags_manager_queue_name
+    attr_accessor :script_tags_manager_queue_name
     attr_accessor :webhooks_manager_queue_name
 
     # configure myshopify domain for local shopify development
@@ -58,7 +58,7 @@ module ShopifyApp
       @root_url = "/"
       @myshopify_domain = "myshopify.com"
       @unified_admin_domain = "shopify.com"
-      @scripttags_manager_queue_name = Rails.application.config.active_job.queue_name
+      @script_tags_manager_queue_name = Rails.application.config.active_job.queue_name
       @webhooks_manager_queue_name = Rails.application.config.active_job.queue_name
       @disable_webpacker = ENV["SHOPIFY_APP_DISABLE_WEBPACKER"].present?
       @scope = []
@@ -115,8 +115,8 @@ module ShopifyApp
       webhooks.present?
     end
 
-    def has_scripttags?
-      scripttags.present?
+    def has_script_tags?
+      script_tags.present?
     end
 
     def requires_billing?

data/lib/shopify_app/controller_concerns/login_protection.rb

@@ -85,13 +85,7 @@ module ShopifyApp
         # Make sure the shop is set in the redirection URL
         unless params[:shop]
           ShopifyApp::Logger.debug("Setting current shop session")
-          params[:shop] = if current_shopify_session
-            current_shopify_session.shop
-
-          elsif shopify_id_token
-            jwt_payload = ShopifyAPI::Auth::JwtPayload.new(shopify_id_token)
-            jwt_payload.shop
-          end
+          params[:shop] = current_shopify_session&.shop || parse_shop_from_jwt
         end
 
         url ||= login_url_with_optional_shop
@@ -269,7 +263,7 @@ module ShopifyApp
       return ShopifyAPI::Context.load_private_session if ShopifyAPI::Context.private?
 
       session_id = ShopifyAPI::Utils::SessionUtils.current_session_id(shopify_id_token, cookies, is_online)
-      return nil unless session_id
+      return unless session_id
 
       ShopifyApp::SessionRepository.load_session(session_id)
     end
@@ -279,5 +273,15 @@ module ShopifyApp
         request.media_type == "text/javascript" ||
         request.media_type == "application/javascript"
     end
+
+    def parse_shop_from_jwt
+      return nil unless shopify_id_token
+
+      jwt_payload = ShopifyAPI::Auth::JwtPayload.new(shopify_id_token)
+      jwt_payload.shop
+    rescue ShopifyAPI::Errors::InvalidJwtTokenError
+      ShopifyApp::Logger.warn("Invalid JWT token for current Shopify session")
+      nil
+    end
   end
 end

data/lib/shopify_app/engine.rb

@@ -5,7 +5,7 @@ module ShopifyApp
     private
 
     def args_info(job)
-      log_disabled_classes = ["ShopifyApp::WebhooksManagerJob"]
+      log_disabled_classes = ["ShopifyApp::WebhooksManagerJob", "ShopifyApp::ScriptTagsManagerJob"]
       return "" if log_disabled_classes.include?(job.class.name)
 
       super
@@ -16,10 +16,6 @@ module ShopifyApp
     engine_name "shopify_app"
     isolate_namespace ShopifyApp
 
-    initializer "shopify_app.middleware" do |app|
-      app.config.middleware.insert_after(::Rack::Runtime, ShopifyApp::JWTMiddleware)
-    end
-
     initializer "shopify_app.assets.precompile" do |app|
       app.config.assets.precompile += [
         "shopify_app/redirect.js",
@@ -30,6 +26,7 @@ module ShopifyApp
       ActiveSupport.on_load(:active_job) do
         if ActiveJob::Base.respond_to?(:log_arguments?)
           WebhooksManagerJob.log_arguments = false
+          ScriptTagsManagerJob.log_arguments = false
         elsif ActiveJob::Logging::LogSubscriber.private_method_defined?(:args_info)
           ActiveJob::Logging::LogSubscriber.prepend(RedactJobParams)
         end

data/lib/shopify_app/errors.rb

@@ -31,4 +31,6 @@ module ShopifyApp
   class ShopifyDomainNotFound < StandardError; end
 
   class ShopifyHostNotFound < StandardError; end
+
+  class RefreshTokenExpiredError < StandardError; end
 end