livechat 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3784d2aa4059d1cc6faa8b79321ef0ec669dd69fac0b5543a3b881a5342b1961
-  data.tar.gz: d31ff12aa8a32a70315f38216fa4c423f0e130147e21bde0473ae189f337ed45
+  metadata.gz: d5968fc9db00037cc2e6330c09e1de36d1f7089bb9649972fd6371ae0349248a
+  data.tar.gz: 193702a94032278baa4d1c5162b8e5f03aa309803b760edb1036ddf1bfbe222f
 SHA512:
-  metadata.gz: b9a7ceca8836ce9238635a4dce4083eb5e04c60d1fb8241957b85a7c2ac5bff69099a8f19ceee1fa7075f1177075511790e783c9ff41df75cb01651a826f9ce0
-  data.tar.gz: 6fe9125a8525af6a62d4e40f728a4260d12aba7bcef2bc9fb75f12eb89fea1ebe1f75b125c20b47a36597eebe91321e3d94d4d43fe622912e35aea42ae34bb26
+  metadata.gz: a3a7a2d524aacbfe4287e89ba4fd3c4714a94df8e00731fd00d375ab1a0c658b36b5272860a9bc56d92401f15d4dff0804987f7de5d0e421825f939e0fc42661
+  data.tar.gz: 81a4123e0a17426d009c68f6f3f31199e46e9d2ed6a6b837eea2ffe4ed5d36361b9cc671989c8a4ffb6b1a6ededd7d246b92727ab656af25b6ede80779b6f284

data/AGENTS.md

@@ -119,9 +119,24 @@ For an account-erasure request, destroy that user's conversations with
 email notifications and hook destinations separately. The content-type
 allowlist is not malware scanning.
 
+### Embedding on a static site
+
+A marketing site that proxies the mount path through to Rails gets the widget from one tag:
+
+```html
+<script src="/livechat/embed.js" defer></script>
+```
+
+Add `?locale=de` for a translated page. Two requirements, and both are load-bearing:
+
+1. **Same origin.** The widget sends `credentials: "same-origin"`, so a cross-origin `<script src>` loads and then silently fails to carry the visitor cookie. Proxy `/livechat/*` from the static site to Rails; do not point the tag at another host.
+2. **`config.allowed_embed_origins = ["https://example.com"]`.** A static page cannot mint a CSRF token, so a request from a listed origin is exempted. Safe because `Origin` is browser-set and unforgeable by page script, it covers only the visitor endpoints, and a request with no `Origin` is never treated as embedded.
+
+Give that surface its own wording with a callable — `config.greeting = ->(request) { ... }` keyed on `request.origin`.
+
 ### Do not
 
-- **Do not copy the widget JavaScript into `app/javascript`, or add a `<script>` tag for it.** `livechat_tag` renders what is needed, and the engine serves the code with a content fingerprint. There is no build step and nothing for esbuild/importmap/Tailwind to know about.
+- **Do not copy the widget JavaScript into `app/javascript`, or add a `<script>` tag for it.** `livechat_tag` renders what is needed (on a page Rails does not render, use `embed.js` above — still not a copy), and the engine serves the code with a content fingerprint. There is no build step and nothing for esbuild/importmap/Tailwind to know about.
 - **Do not rebuild the inbox, and do not edit views inside the gem.** To put it inside an admin you already have, set `config.base_controller_class = "Admin::BaseController"` — it inherits that controller's layout, helpers, authentication and request context. For the shell alone, `config.agent_layout = "admin/application"`. Both work with nothing else wired up: the inbox's own assets are declared by its views, not the layout.
 - **Do not add an Action Cable mount to "make chat realtime"** unless you also set `config.action_cable = true`. Polling is the default and is not broken.
 - **Do not set config outside the initializer.** `rate_limit` in particular is read when the controller class loads; assigning config per-request mutates it process-wide.
@@ -139,9 +154,10 @@ Everything is optional; a fresh install works with zero config. Full list with c
 | `current_user` | `nil` | Receives the request; nil means guest-by-cookie |
 | `visitor_label`, `agent_label` | name/email/to_s | Receive the user |
 | `agent_display_name` | the label unchanged | Receives the label; return "Support team" to keep agents anonymous |
-| `app_name`, `greeting`, `reply_time_text`, `launcher_label` | localized defaults | Widget copy |
-| `avatar_url`, `accent_color` | `nil` | Header avatar (URL or callable) and brand hex |
-| `show_launcher` | `true` | `false` = open only from your own elements |
+| `app_name`, `greeting`, `reply_time_text`, `launcher_label` | localized defaults | Widget copy. All but `app_name` also take a callable receiving the request |
+| `avatar_url`, `accent_color` | `nil` | Header avatar (URL or callable) and brand hex (also callable) |
+| `show_launcher` | `true` | `false` = open only from your own elements. Also takes a callable |
+| `allowed_embed_origins` | `[]` | Origins that may embed the widget on a page this app does not render |
 | `mailer_from` | `nil` | **Required for any email at all** |
 | `agent_emails` | `nil` | Array or callable |
 | `attach_files` | `true` | Needs Active Storage; inert without it |
@@ -167,6 +183,8 @@ Turbo Drive and strict nonce-based CSP work out of the box. 26 locales ship with
 | Messages only appear on refresh | Expected: polling is the default. `config.action_cable = true` (with `/cable` mounted) for push |
 | No attachment button | Active Storage not installed, or `attach_files = false` |
 | `undefined local variable current_user` in the initializer | A gate lambda treated its argument as a controller. It is a `request` |
+| Widget loads on a static site but every message 422s | The embedding origin is not in `allowed_embed_origins`. A static page has no CSRF token |
+| Widget on a static site never finds its thread | It is pointed at another origin. The widget sends `credentials: "same-origin"` — proxy the mount path instead of linking across hosts |
 
 ---
 

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 1.1.0 - 2026-09-25
+
+- **The widget can now live on a site this app does not render.** A static
+  marketing site that proxies the mount path through to Rails loads the whole
+  widget from one tag — `<script src="/livechat/embed.js" defer>` — and never
+  reproduces the config block itself. `?locale=` picks the copy. The response is
+  never cached; the widget code it pulls in stays immutably cached as before.
+- Added `config.allowed_embed_origins`. A page served from a listed origin
+  cannot carry a Rails CSRF token, so a matching request is exempted from
+  forgery protection. The exemption rests on the `Origin` header, which the
+  browser sets and page script cannot forge; it covers only the widget's own
+  visitor endpoints, never the inbox; and a request that sends no `Origin` at
+  all — curl, a server-side client — is never treated as embedded.
+- Added `Livechat.public_paths`: the endpoints that answer with JavaScript, JSON
+  or a file and need no Rails session. Hosts that mint a CSP nonce (or anything
+  else) from the session per request can skip these, rather than handing a
+  cookie to every visitor who only ever loaded the page.
+- `greeting`, `reply_time_text`, `launcher_label`, `show_launcher` and
+  `accent_color` each accept a callable receiving the request, the way
+  `avatar_url` already did. One app serving both an in-app widget and an
+  embedded one can greet each surface differently, and show the bubble on one
+  but not the other.
+
 ## 1.0.0 - 2026-08-11
 
 - **The 1.x record names are settled.** `Livechat::Conversation` and

data/README.md

@@ -136,6 +136,7 @@ Everything is optional — a fresh install works with zero config. In
 | `avatar_url` | `nil` | Customer-facing avatar in the widget header; URL or per-request callable |
 | `accent_color` | `nil` | One hex restyles launcher, header, bubbles, send button |
 | `show_launcher` | `true` | `false` hides the bubble — bring your own entry point |
+| `allowed_embed_origins` | `[]` | Origins allowed to embed the widget on a page this app doesn't render |
 | `visitor_label` | name, else email | How a visitor is labelled in the inbox |
 | `agent_label` | name, else email | How an agent is labelled internally |
 | `agent_display_name` | the full label | What **visitors** see — trim it or anonymise it |
@@ -167,7 +168,9 @@ Livechat.configure do |config|
 end
 ```
 
-`avatar_url` can also choose branding from the current request:
+`avatar_url`, `greeting`, `reply_time_text`, `launcher_label`, `show_launcher`
+and `accent_color` each take a callable receiving the request, so one app can
+brand or word the widget per tenant — or per surface:
 
 ```ruby
 config.avatar_url = ->(request) { request.env["current_account"]&.support_avatar_url }
@@ -245,6 +248,66 @@ config.storage_service = :livechat_uploads
 
 </details>
 
+## On a site this app doesn't render
+
+Marketing sites are usually static and live on their own host, which is exactly
+where people ask presales questions. The widget can go there too, with one tag:
+
+```html
+<script src="/livechat/embed.js" defer></script>
+```
+
+`embed.js` carries the config block the layout helper would have rendered and
+pulls in the widget, so the static page never reproduces engine markup that a
+future release might change. Add `?locale=de` for a translated site.
+
+Two things have to be true.
+
+**The mount path must be same-origin with that site.** The widget sends
+`credentials: "same-origin"`, so a cross-origin script tag would load and then
+quietly fail to carry the visitor's cookie. Proxy `/livechat/*` from the static
+site through to Rails — one rule on a CDN, one `location` block in nginx — and
+the browser sees a single origin.
+
+**The embedding origin must be allowlisted**, because a static page cannot mint
+a CSRF token:
+
+```ruby
+config.allowed_embed_origins = ["https://example.com"]
+```
+
+`Livechat.public_paths` lists the endpoints that need no Rails session — the
+widget script, the embed bootstrap, the visitor API and attachments. If your app
+touches the session on every request (a CSP nonce generator usually does), skip
+them there, or every visitor who merely loads a page leaves with a cookie:
+
+```ruby
+config.content_security_policy_nonce_generator = lambda do |request|
+  next if Livechat.public_paths.any? { |path| request.path.start_with?(path) }
+  request.session[:csp_nonce] ||= SecureRandom.hex(16)
+end
+```
+
+A request from a listed origin skips forgery protection. What makes that safe is
+that `Origin` is set by the browser and cannot be forged by page script, so
+listing an origin grants nothing to any other site; the exemption covers only
+the widget's visitor endpoints and never the inbox; and a request with no
+`Origin` header at all is never treated as embedded, so a non-browser client
+gains nothing.
+
+Marketing visitors usually want a different greeting from signed-in users, and
+the same app serves both:
+
+```ruby
+config.greeting = lambda do |request|
+  if request.origin == "https://example.com"
+    "Questions before you buy? Ask away."
+  else
+    "Hi! How can we help?"
+  end
+end
+```
+
 ## Privacy, retention, and deletion
 
 Livechat stores conversation identity and context, message bodies and
@@ -340,6 +403,9 @@ stable under semantic versioning:
 - `Livechat.configure`, `mount_livechat`, `livechat_tag`, `livechat_button`,
   `window.Livechat.open/close`, `data-livechat-open`, and
   `data-livechat-message`.
+- The `embed.js` endpoint under the mount path, including its `locale`
+  parameter. The markup it writes is private — embed the endpoint, not a copy
+  of its output.
 - `config.on_visitor_message` and `config.on_agent_message`, each called with
   the saved `Livechat::Message` documented by the initializer.
 

data/app/controllers/livechat/application_controller.rb

@@ -13,5 +13,14 @@ module Livechat
     include RequestContext
 
     protect_from_forgery with: :exception
+
+    private
+
+    # A page on an allowlisted embed origin is static and has no Rails session
+    # to mint a token from, so the Origin header stands in for one. Only this
+    # controller's descendants are affected — the inbox verifies as usual.
+    def verified_request?
+      Livechat.embedded?(request) || super
+    end
   end
 end

data/app/controllers/livechat/widgets_controller.rb

@@ -20,6 +20,27 @@ module Livechat
       serve(Widget.javascript, Widget.fingerprint)
     end
 
+    # Bootstraps the widget on a page this app does not render. Carries the
+    # config the layout helper would have rendered, so an external page needs
+    # one <script src> and nothing that has to keep up with this engine.
+    #
+    # Never cached: it reflects the current visitor and whatever copy the host
+    # resolves per request. The heavy widget.js it pulls in stays immutable.
+    def embed
+      body = if Livechat.enabled?(request)
+               I18n.with_locale(embed_locale) do
+                 Widget.embed_javascript(locale: I18n.locale,
+                                         authenticated: current_visitor.present?,
+                                         settings: Livechat.settings_for(request))
+               end
+             else
+               ''
+             end
+
+      response.headers['Cache-Control'] = 'no-store'
+      render plain: body, content_type: 'text/javascript'
+    end
+
     def dashboard
       serve(Widget.dashboard_javascript, Widget.dashboard_fingerprint, 'text/javascript')
     end
@@ -30,6 +51,14 @@ module Livechat
 
     private
 
+    # An embedding site carries its own language; it asks for the matching
+    # copy with ?locale=. Anything the host does not actually have falls back
+    # rather than raising.
+    def embed_locale
+      requested = params[:locale].to_s
+      I18n.available_locales.map(&:to_s).include?(requested) ? requested : I18n.locale
+    end
+
     def serve(source, fingerprint, content_type = 'text/javascript')
       expires_in 1.year, public: true if params[:v] == fingerprint
       return unless stale?(etag: [Livechat::VERSION, fingerprint])

data/config/routes.rb

@@ -2,6 +2,7 @@
 
 Livechat::Engine.routes.draw do
   get 'widget.js', to: 'widgets#show', as: :widget
+  get 'embed.js', to: 'widgets#embed', as: :embed
   get 'dashboard.js', to: 'widgets#dashboard', as: :dashboard_script
   get 'dashboard.css', to: 'widgets#dashboard_stylesheet', as: :dashboard_stylesheet
 

data/lib/livechat/configuration.rb

@@ -61,6 +61,9 @@ module Livechat
 
     # Widget copy. nil uses the localized defaults. reply_time_text is the
     # honest line under the greeting — "We usually reply within a few hours."
+    # A String, or a callable receiving the request: one app serving both an
+    # in-app widget and an embedded one on a marketing site needs to greet
+    # those visitors differently.
     attr_accessor :greeting, :reply_time_text, :launcher_label
 
     # Optional customer-facing avatar shown in the widget header. Use a URL
@@ -70,13 +73,29 @@ module Livechat
 
     # Brand color for the widget (launcher, header, visitor bubbles, send
     # button) as a hex value, e.g. "#7c3aed". The widget picks black or white
-    # text automatically for contrast. nil keeps the built-in blue.
+    # text automatically for contrast. nil keeps the built-in blue. A callable
+    # receiving the request works too.
     attr_accessor :accent_color
 
     # The floating launcher bubble. Set false to open the widget only from
-    # your own elements carrying `data-livechat-open`.
+    # your own elements carrying `data-livechat-open`. Also accepts a callable
+    # receiving the request, for a host that wants the bubble on one surface
+    # and its own opener on another.
     attr_accessor :show_launcher
 
+    # Origins allowed to embed the widget on pages this app does not render —
+    # a static marketing site that proxies `mount_path` through to this app,
+    # say. An Array of origins ("https://example.com"), or a callable
+    # receiving the request and returning one.
+    #
+    # Such a page cannot carry a Rails CSRF token, so a matching request is
+    # exempted from forgery protection. That exemption rests on the Origin
+    # header, which the browser sets and script cannot forge, and applies only
+    # to the widget's own visitor endpoints — never to the inbox. A request
+    # arriving without an Origin at all (curl, a server-side client) is never
+    # embedded and keeps the full check.
+    attr_accessor :allowed_embed_origins
+
     # Email addresses to notify when a visitor writes and nobody has read it —
     # an array, or a callable returning one. nil disables the built-in email.
     attr_accessor :agent_emails
@@ -140,6 +159,7 @@ module Livechat
       @avatar_url = nil
       @accent_color = nil
       @show_launcher = true
+      @allowed_embed_origins = []
       @agent_emails = nil
       @mailer_from = nil
       @on_visitor_message = ->(_message) {}

data/lib/livechat/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Livechat
-  VERSION = '1.0.0'
+  VERSION = '1.1.0'
 end

data/lib/livechat/widget.rb

@@ -58,29 +58,54 @@ module Livechat
       # nonce gets refused; a same-origin src is covered by `'self'` on every
       # visit. `nonce:` is still stamped for hosts whose script-src has no
       # 'self'; pass nil when the app has no nonce.
-      def snippet(locale:, authenticated:, avatar_url: nil, nonce: nil)
-        json = config_json(locale:, authenticated:, avatar_url:)
+      def snippet(locale:, authenticated:, settings: nil, nonce: nil)
+        json = config_json(locale:, authenticated:, settings:)
         nonce_attr = nonce ? %( nonce="#{nonce}") : ''
-        src = "#{Livechat.config.mount_path.chomp('/')}/widget.js?v=#{fingerprint}"
 
         %(<script type="application/json" data-livechat-config>#{json}</script>) +
-          %(<script src="#{src}" defer#{nonce_attr} data-livechat-widget></script>)
+          %(<script src="#{script_src}" defer#{nonce_attr} data-livechat-widget></script>)
       end
 
-      def config_json(locale:, authenticated:, avatar_url: nil)
+      # The same two tags, assembled by the browser instead of by a Rails
+      # template. A page this app does not render — a static marketing site
+      # proxying the mount path through to Rails — gets the widget from one
+      # plain <script src>, and never reproduces the config block itself.
+      def embed_javascript(locale:, authenticated:, settings: nil)
+        <<~JS
+          /* livechat embed */
+          (function () {
+            if (window.__livechatEmbedded) return;
+            window.__livechatEmbedded = true;
+
+            var config = document.createElement("script");
+            config.type = "application/json";
+            config.setAttribute("data-livechat-config", "");
+            config.textContent = JSON.stringify(#{config_json(locale:, authenticated:, settings:)});
+            document.head.appendChild(config);
+
+            var widget = document.createElement("script");
+            widget.src = #{script_src.to_json};
+            widget.setAttribute("data-livechat-widget", "");
+            document.head.appendChild(widget);
+          })();
+        JS
+      end
+
+      def config_json(locale:, authenticated:, settings: nil)
         config = Livechat.config
+        settings ||= Livechat.settings_for(nil)
         payload = {
           endpoint: config.widget_endpoint,
           locale: locale.to_s,
           rtl: rtl?(locale),
           authenticated: authenticated ? true : false,
-          launcher: config.show_launcher ? true : false,
+          launcher: settings[:show_launcher] ? true : false,
           appName: Livechat.app_name,
-          avatarUrl: avatar_url,
-          accentColor: config.accent_color,
+          avatarUrl: settings[:avatar_url],
+          accentColor: settings[:accent_color],
           attachments: Livechat.attachments_enabled?,
           maxAttachments: config.max_attachments,
-          labels: labels
+          labels: labels(settings)
         }
         # Escape "</" so a value can't close the <script> block early.
         payload.to_json.gsub('</', '<\/')
@@ -88,16 +113,19 @@ module Livechat
 
       private
 
+      def script_src
+        "#{Livechat.config.mount_path.chomp('/')}/widget.js?v=#{fingerprint}"
+      end
+
       # Every user-facing string in the widget, resolved through Rails I18n so
       # the chat follows the app's current locale. Each lookup carries an
       # English default, so the widget stays fully worded even when a key is
       # missing for the active locale.
-      def labels
-        config = Livechat.config
+      def labels(settings)
         {
-          launcher: config.launcher_label.presence || t(:launcher, 'Chat with us'),
-          greeting: config.greeting.presence || t(:greeting, 'Hi! How can we help?'),
-          replyTime: config.reply_time_text.presence ||
+          launcher: settings[:launcher_label].presence || t(:launcher, 'Chat with us'),
+          greeting: settings[:greeting].presence || t(:greeting, 'Hi! How can we help?'),
+          replyTime: settings[:reply_time_text].presence ||
             t(:reply_time, 'We usually reply within a few hours.'),
           placeholder: t(:placeholder, 'Write a message…'),
           send: t(:send, 'Send'),

data/lib/livechat/widget_helper.rb

@@ -12,7 +12,7 @@ module Livechat
       Widget.snippet(
         locale: I18n.locale,
         authenticated: livechat_visitor.present?,
-        avatar_url: livechat_avatar_url,
+        settings: Livechat.settings_for(request),
         nonce: (content_security_policy_nonce if respond_to?(:content_security_policy_nonce))
       ).html_safe
     end
@@ -33,12 +33,6 @@ module Livechat
 
     private
 
-    def livechat_avatar_url
-      value = Livechat.config.avatar_url
-      value = value.call(request) if value.respond_to?(:call)
-      value.to_s.presence
-    end
-
     def livechat_visitor
       return @livechat_visitor if defined?(@livechat_visitor)
 

data/lib/livechat.rb

@@ -30,6 +30,49 @@ module Livechat
       !!config.enabled.call(request)
     end
 
+    # The engine's public surface: the widget script, the embed bootstrap, the
+    # visitor API and the attachment route. All of them answer with JavaScript,
+    # JSON or a file, and none of them need a Rails session.
+    #
+    # Exposed because a host usually has session, CSP or caching rules written
+    # for its own HTML pages, and applying those here costs every visitor a
+    # cookie for a request that never had a use for one.
+    def public_paths
+      mount = config.mount_path.chomp('/')
+      ["#{mount}/widget.js", "#{mount}/embed.js", "#{mount}/widget/", "#{mount}/attachments/"]
+    end
+
+    # Resolve a setting that may be a plain value or a per-request callable.
+    def resolve(value, request)
+      value.respond_to?(:call) ? value.call(request) : value
+    end
+
+    # The per-request widget settings a host may vary by surface. Resolved by
+    # the helper and by the embed script, so both routes see the same values.
+    def settings_for(request)
+      {
+        greeting: resolve(config.greeting, request),
+        reply_time_text: resolve(config.reply_time_text, request),
+        launcher_label: resolve(config.launcher_label, request),
+        show_launcher: resolve(config.show_launcher, request),
+        accent_color: resolve(config.accent_color, request),
+        avatar_url: resolve(config.avatar_url, request).to_s.presence
+      }
+    end
+
+    # Is this request coming from a page on an allowlisted external origin?
+    #
+    # Only ever true for a request the browser stamped with a matching Origin.
+    # A missing Origin is not a match: a non-browser client must not inherit a
+    # browser-guaranteed exemption.
+    def embedded?(request)
+      origin = request.origin.presence
+      return false unless origin
+
+      allowed = resolve(config.allowed_embed_origins, request)
+      Array(allowed).any? { |candidate| candidate.to_s.chomp('/') == origin.chomp('/') }
+    end
+
     # Can this request work the inbox? Checked by every inbox action.
     # The class Livechat::DashboardController inherits from. Resolved on every
     # call rather than memoized, so a host that reassigns base_controller_class

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: livechat
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Yaroslav Shmarov
@@ -138,7 +138,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: 'Open-source live chat for Rails: a drop-in support widget plus a team inbox,
   in your own database.'