livechat 0.10.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f7868af4ac547374ec04ba6aac09d12db7f9ae53776cceb7967cc32c7bf56ef
-  data.tar.gz: 40faba066cf75b325672728f1317a9dd1e56771cb2436c1e3a621ad36a560516
+  metadata.gz: d5968fc9db00037cc2e6330c09e1de36d1f7089bb9649972fd6371ae0349248a
+  data.tar.gz: 193702a94032278baa4d1c5162b8e5f03aa309803b760edb1036ddf1bfbe222f
 SHA512:
-  metadata.gz: 429aaa62a6b365b2314c2193faa3377879aee0b0c564c935065cc4df798e5471a5571c7e2f8b229fec2490b6ca382dfe8e50c2d88d809c063b5bf83b8d9183c3
-  data.tar.gz: 8658bd68fe0bfd233f3ddddd30079bd71f6443394650c306171ecc7db2184602e93bff51622d049b1e0d33b6e355676e077eab8177f9c3c833a13f924cbd71d8
+  metadata.gz: a3a7a2d524aacbfe4287e89ba4fd3c4714a94df8e00731fd00d375ab1a0c658b36b5272860a9bc56d92401f15d4dff0804987f7de5d0e421825f939e0fc42661
+  data.tar.gz: 81a4123e0a17426d009c68f6f3f31199e46e9d2ed6a6b837eea2ffe4ed5d36361b9cc671989c8a4ffb6b1a6ededd7d246b92727ab656af25b6ede80779b6f284

data/AGENTS.md

@@ -5,7 +5,7 @@ Instructions for coding agents. Two audiences:
 - **[Installing livechat into a Rails app](#installing-into-a-rails-app)** — you are working in a host app and were asked to add support chat, live chat, or an in-app inbox.
 - **[Working on the gem itself](#working-on-the-gem-itself)** — you are working in this repository.
 
-Requirements: Ruby >= 3.2, Rails >= 7.1. Active Storage only for file attachments. **No Redis and no Action Cable** — the transport is polling unless you opt in.
+Requirements: Ruby >= 3.2, Rails >= 7.1 and < 9. Active Storage only for file attachments. **No Redis and no Action Cable** — the transport is polling unless you opt in.
 
 If you are in a host app and this file is not in front of you, it ships inside the gem: `cat "$(bundle show livechat)/AGENTS.md"`.
 
@@ -104,9 +104,39 @@ Leave it off unless the app already has Action Cable working. Polling is not a d
 
 `config.attach_files` is on by default but **silently inert without Active Storage** in the host app (`rails active_storage:install`) — the widget keeps working, just without a paperclip. Caps: `max_attachments` (5), `max_attachment_size` (10 MB), `allowed_attachment_types` (nil = any). Files are served through the engine at `/livechat/attachments/:id`, gated per request — never a public blob URL. Do not build your own blob links.
 
+Every authorized agent can read every conversation; visitor reads are scoped to
+the signed-in id or guest cookie. There is no tenant-isolated agent inbox in
+1.x. No retention job runs automatically. Hosts should schedule their own
+cutoff and use the destroy lifecycle so messages and attachments follow it:
+
+```ruby
+Livechat::Conversation.purge_resolved(older_than: 90.days.ago)
+```
+
+For an account-erasure request, destroy that user's conversations with
+`where(visitor_id: user.id.to_s).find_each(&:destroy!)`. Do not use
+`delete_all` when attachments must be purged. Confirm storage jobs, backups,
+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.
@@ -124,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 |
@@ -152,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 |
 
 ---
 
@@ -161,8 +194,14 @@ Turbo Drive and strict nonce-based CSP work out of the box. 26 locales ship with
 
 ## Working on the gem itself
 
+The development toolchain is pinned to Ruby 4.0.5 in `mise.toml`. Do not use
+macOS's `/usr/bin/ruby`. In shells, hooks, or automation where mise activation
+is uncertain, explicitly prepend the configured Ruby, for example
+`PATH="$(mise where ruby)/bin:$PATH" bundle exec rake test`.
+
 ```bash
 bundle exec rake test            # minitest, dummy app under test/dummy
+bundle exec rake test:system     # real headless-Chrome visitor/agent loop
 bundle exec rubocop              # must be clean
 BUNDLE_GEMFILE=gemfiles/rails_7.1.gemfile bundle exec rake test   # 7.1, 7.2, 8.0, 8.1 in gemfiles/
 ```

data/CHANGELOG.md

@@ -1,5 +1,63 @@
 # 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
+  `Livechat::Message` are now documented as stable model constants rather than
+  being collapsed into a generic `Post`; the distinction preserves the thread
+  aggregate and the messages it owns.
+- **A real Chrome test now proves the core support loop:** a visitor opens the
+  widget and sends a message, an agent reads and answers it in the inbox, and
+  the same visitor sees the reply back in the widget. Capybara and Selenium are
+  development/test dependencies only.
+- **Attachments stay behind the conversation gate.** Full and byte-range data
+  now streams directly with a private, `no-store` cache policy after the
+  request is authorized. The URL is unchanged; audio playback gains seeking,
+  and no reusable Active Storage service URL leaves the engine.
+- Added `Livechat::Conversation.purge_resolved(older_than:)` for explicit host
+  retention jobs. It destroys only resolved conversations older than the
+  supplied cutoff, cascades through messages and the configured Active Storage
+  lifecycle, and returns the number destroyed. Nothing is deleted
+  automatically.
+- Added a security policy documenting stored visitor/message data, the shared
+  agent-inbox boundary, attachment risks, notifications, deletion, retention,
+  and private vulnerability reporting. Submitted page URLs now accept only
+  HTTP(S) and drop credentials, query strings, and fragments before storage,
+  keeping tokens out of the database and notification emails.
+- Hosts that load Action View from an initializer boot normally. The widget
+  helper is loaded from `lib` before the engine registers its Action View hook;
+  `livechat_tag` and `livechat_button` are unchanged.
+- Supported combinations are Ruby 3.2 through 4.0 and Rails 7.1 through 8.1;
+  Rails now has a `< 9` upper bound. Release validation runs the browser test,
+  lint and JavaScript checks, builds the gem, verifies RubyGems indexing, and
+  creates the GitHub Release.
+- Existing 0.x installs need no migration, initializer change, constant alias,
+  or model rename. The new Rails upper bound, query-free stored page URLs, and
+  direct attachment streaming behavior are the compatibility costs.
+
 ## 0.10.1
 
 - **The demo inbox is now a live setup walkthrough.** The open conversation

data/README.md

@@ -50,7 +50,7 @@ demo messages instead of duplicating conversations.
 > The inbox defaults to **development only**. Set `authorize_agent` before you
 > deploy — see [Configure](#configure).
 
-Ruby >= 3.2 · Rails >= 7.1 · Active Storage only if you want file attachments.
+Ruby >= 3.2 · Rails >= 7.1, < 9 · Active Storage only if you want file attachments.
 
 Installing with a coding agent? Point it at [AGENTS.md](AGENTS.md) — the same
 steps in the order an agent needs them, plus the gates it tends to get wrong and
@@ -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 }
@@ -228,10 +231,11 @@ bin/rails active_storage:install && bin/rails db:migrate
 ```
 
 Visitors get a paperclip in the composer; agents get a file field on the reply
-form. Images render inline, other files as download links. Every file is served
+form. Safe image formats render inline, other files as download links. Every file is served
 through the engine's own route and gated the same way the chat is — an agent,
 or the visitor who owns that conversation — so nothing leaks through a
-guessable or long-lived blob URL.
+guessable or long-lived blob URL. Responses are private and `no-store`; audio
+supports byte ranges for playback and seeking.
 
 Where Active Storage isn't installed, the widget quietly stays text-only.
 
@@ -244,6 +248,98 @@ 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
+attribution, read/status timestamps, and optional attachments in the host
+application. Captured page URLs are limited to HTTP(S) and stored without
+credentials, query strings, or fragments. The engine does not send data to a
+Livechat service, but configured notification emails and message hooks can send
+message content, visitor context, and attachment filenames wherever the host
+chooses.
+
+Every authorized agent can read every conversation in this one shared inbox.
+Visitors can read only the conversation resolved from their signed-in id or
+guest cookie. Livechat does not provide tenant-isolated agent inboxes in 1.x;
+do not use one mount for mutually isolated tenant support teams.
+
+No record is deleted automatically. Delete one conversation (including its
+messages), all conversations for a user, or resolved history past a host-chosen
+cutoff explicitly:
+
+```ruby
+Livechat::Conversation.find(id).destroy!
+Livechat::Conversation.where(visitor_id: user.id.to_s).find_each(&:destroy!)
+Livechat::Conversation.purge_resolved(older_than: 90.days.ago)
+```
+
+Use `destroy!`, not `delete_all`, when attachments must follow Rails' Active
+Storage lifecycle. Confirm object-storage jobs, replicas, backups, notification
+emails, hook destinations, logs, and exports separately: deleting live database
+rows cannot retract those copies. `allowed_attachment_types` is an upload
+allowlist, not malware scanning; choose a restrictive list and storage policy
+for your application. See [SECURITY.md](SECURITY.md) for the full boundary.
+
 <details>
 <summary><b>Realtime with Action Cable</b></summary>
 
@@ -293,6 +389,39 @@ Contextual buttons are where a Rails app beats a generic support widget:
 </button>
 ```
 
+## Compatibility and public API
+
+The following are the model and integration contracts that 1.x will keep
+stable under semantic versioning:
+
+- `Livechat::Conversation`, including `STATUSES`, `TYPING_TTL`, its persisted
+  fields, `messages`, `recent_first`, `for_visitor`, `claim!`, posting and
+  read/status methods, `display_name`, and `purge_resolved`.
+- `Livechat::Message`, including `AUTHOR_TYPES`, `EVENTS`, `MAX_BODY_LENGTH`,
+  its persisted fields, optional `files`, documented scopes, author/read
+  predicates, `public_label`, `attached_files`, and `preview`.
+- `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.
+
+`Conversation` and `Message` are intentionally distinct and will not become a
+generic `Post` during 1.x. Engine controllers, partials, CSS classes, generated
+HTML, and widget implementation objects are private. Incompatible changes to
+the public list above wait for a new major version; a deprecation normally
+ships first.
+
+### Upgrading from 0.x
+
+There is no migration, initializer change, constant alias, or model rename.
+Stored page URLs become query-free on the next visitor message, attachment
+responses stay on the same engine URL but now stream privately instead of being
+buffered, and Rails 9 is excluded until a compatible release is tested.
+
 ## Use cases
 
 - SaaS apps: answer billing, onboarding and account questions from inside the app.
@@ -313,6 +442,7 @@ worth of exactly that.
 
 ```bash
 bundle exec rake test
+bundle exec rake test:system
 bundle exec rubocop
 ```
 

data/Rakefile

@@ -5,7 +5,15 @@ require 'rake/testtask'
 
 Rake::TestTask.new(:test) do |t|
   t.libs << 'test'
-  t.pattern = 'test/**/*_test.rb'
+  t.test_files = FileList['test/**/*_test.rb'].exclude('test/system/**/*')
+end
+
+namespace :test do
+  desc 'Run browser (system) tests'
+  Rake::TestTask.new(:system) do |task|
+    task.libs << 'test'
+    task.test_files = FileList['test/system/**/*_test.rb']
+  end
 end
 
 task default: :test

data/SECURITY.md

@@ -0,0 +1,71 @@
+# Security policy
+
+## Supported versions
+
+Security fixes are released for the latest 1.x version. If a report also
+affects the newest 0.x release, a backport may be published when the fix is
+small and the affected application cannot upgrade immediately.
+
+## Reporting a vulnerability
+
+Please do not open a public issue for a vulnerability. Use
+[GitHub private vulnerability reporting](https://github.com/yshmarov/livechat/security/advisories/new)
+and include the affected version, a minimal reproduction, impact, and any known
+workaround. Do not include credentials, session cookies, visitor tokens,
+private application URLs, customer messages, uploaded files, or production
+database contents.
+
+Public disclosure should wait until a fixed version is available and affected
+users have had a reasonable opportunity to upgrade.
+
+## Data and authorization boundary
+
+The widget and visitor endpoints are controlled by `config.enabled`; the agent
+inbox is separately protected by `authorize_agent` and fails closed outside
+development until the host grants access. A visitor can read only the
+conversation resolved from their signed-in id or opaque guest cookie. Every
+authorized agent can read and answer every conversation in the mounted inbox.
+Livechat 1.x does not provide tenant-isolated agent inboxes.
+
+Conversations can store a visitor token, host user id and label, email, status,
+query-free HTTP(S) page URL, locale, message preview, activity timestamps, and
+record timestamps. Messages can store bodies, author type, agent id and label,
+system events, read state, timestamps, and optional files. Page credentials,
+query strings, fragments, executable URL schemes, and invalid URLs are not
+stored. Message bodies are plain text and length-capped; rendering escapes
+them rather than interpreting Markdown or HTML.
+
+Attachments stream through the engine only after the request is authorized as
+an agent or the owning visitor. Responses are private and `no-store`, support
+byte ranges, and never redirect to a reusable signed blob URL. Hosts own the
+storage service, bucket policy, backups, retention, malware controls, access
+logs, and incident response. `allowed_attachment_types` is an application
+allowlist, not content inspection or malware scanning.
+
+Livechat has no vendor service and does not transmit conversation data to this
+project. Host-configured notification email can include message content,
+visitor context, and attachment filenames. `on_visitor_message` and
+`on_agent_message` receive the saved message and can send it anywhere the host
+chooses. Those email and hook destinations are part of the host's privacy and
+retention boundary.
+
+## Deletion and retention
+
+Nothing is deleted automatically. Use the Active Record destroy lifecycle so
+messages and Active Storage attachments follow their configured dependencies:
+
+```ruby
+Livechat::Conversation.find(id).destroy!
+Livechat::Conversation.where(visitor_id: user.id.to_s).find_each(&:destroy!)
+Livechat::Conversation.purge_resolved(older_than: 90.days.ago)
+```
+
+`purge_resolved` removes only resolved conversations whose last activity is
+older than the supplied cutoff and returns the number destroyed. Open threads
+are never removed by it. Do not use `delete_all` when dependent messages and
+attachments must be removed.
+
+Active Storage may enqueue blob purging through the host's Active Job adapter.
+Confirm those jobs and deletion from object storage, replicas, backups, caches,
+notification mailboxes, hook destinations, logs, analytics, and exports;
+deleting live database rows does not rewrite those systems.

data/app/controllers/concerns/livechat/request_context.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'uri'
+
 module Livechat
   # Who is asking — visitor or agent — and the gates that answer it.
   #
@@ -55,6 +57,24 @@ module Livechat
       render json: { errors: [message] }, status: :too_many_requests
     end
 
+    # The widget sends window.location.href so an agent knows where the visitor
+    # got stuck. Store only a normal HTTP(S) location, never credentials,
+    # fragments, or query parameters that can carry tokens and customer data.
+    def clean_page_url(value)
+      raw = value.to_s
+      return if raw.blank? || raw.length > 2_048
+
+      uri = URI.parse(raw)
+      return unless %w[http https].include?(uri.scheme&.downcase)
+      return if uri.host.blank? || uri.userinfo.present?
+
+      uri.query = nil
+      uri.fragment = nil
+      uri.to_s.first(255)
+    rescue URI::InvalidURIError
+      nil
+    end
+
     # Guests get a permanent random token — their key to the conversation
     # across visits. Signed-in visitors are keyed by id and only need the
     # cookie to carry a guest history into their account.

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/attachments_controller.rb

@@ -7,6 +7,8 @@ module Livechat
   # visitor whose conversation it belongs to. Streamed inline (not redirected
   # to a signed blob URL), so no long-lived link ever escapes the gate.
   class AttachmentsController < ApplicationController
+    include ActiveStorage::Streaming if defined?(::ActiveStorage::Streaming)
+
     def show
       attachment = find_attachment
       return head :not_found unless attachment
@@ -47,15 +49,72 @@ module Livechat
     end
 
     # Images and audio render inline (so the clients can show native media
-    # controls); anything else downloads. nosniff keeps the browser from
-    # second-guessing the type of a visitor-supplied file.
+    # controls); anything else downloads. Responses are private and never
+    # stored, and byte ranges keep audio seek/playback working without handing
+    # out an Active Storage service URL.
     def stream(blob)
       response.headers['X-Content-Type-Options'] = 'nosniff'
-      inline = blob.content_type.to_s.start_with?('image/', 'audio/')
-      send_data blob.download,
-                filename: blob.filename.to_s,
-                type: blob.content_type.presence || 'application/octet-stream',
-                disposition: inline ? 'inline' : 'attachment'
+      response.headers['Cache-Control'] = 'private, no-store'
+      disposition = inline?(blob) ? 'inline' : 'attachment'
+
+      if request.headers['Range'].present?
+        if inline_audio?(blob)
+          send_audio_byte_range_data(blob, request.headers['Range'])
+        else
+          send_blob_byte_range_data(blob, request.headers['Range'], disposition:)
+        end
+      elsif inline_audio?(blob)
+        stream_audio(blob)
+      else
+        response.headers['Accept-Ranges'] = 'bytes'
+        response.headers['Content-Length'] = blob.byte_size.to_s
+        send_blob_stream(blob, disposition:)
+      end
+    end
+
+    # Active Storage deliberately forces types outside its image/PDF allowlist
+    # to download. The widget's recorded voice notes are a small explicit
+    # exception; nosniff plus an audio Content-Type keeps them media-only.
+    def inline?(blob)
+      AttachmentPolicy.inline?(blob.content_type)
+    end
+
+    def inline_audio?(blob)
+      AttachmentPolicy.audio?(blob.content_type)
+    end
+
+    def stream_audio(blob)
+      response.headers['Accept-Ranges'] = 'bytes'
+      response.headers['Content-Length'] = blob.byte_size.to_s
+      send_stream(filename: blob.filename.sanitized, disposition: 'inline', type: blob.content_type) do |stream|
+        blob.download { |chunk| stream.write(chunk) }
+      end
+    rescue ActiveStorage::FileNotFoundError
+      expires_now
+      head :not_found
+    end
+
+    def send_audio_byte_range_data(blob, range_header)
+      ranges = Rack::Utils.get_byte_ranges(range_header, blob.byte_size)
+      range = ranges.first if ranges&.one?
+      return head :range_not_satisfiable unless range
+      return head :range_not_satisfiable if range.end - range.begin >= streaming_chunk_max_size
+
+      data = blob.download_chunk(range)
+      response.headers['Content-Range'] = "bytes #{range.begin}-#{range.end}/#{blob.byte_size}"
+      response.headers['Accept-Ranges'] = 'bytes'
+      response.headers['Content-Length'] = data.bytesize.to_s
+      send_data data, filename: blob.filename.sanitized, disposition: 'inline',
+                      status: :partial_content, type: blob.content_type
+    end
+
+    # Rails 8 exposes this knob; Rails 7.1/7.2 do not. Match the newer default
+    # on older supported releases so a Range header cannot force an unbounded
+    # in-memory chunk.
+    def streaming_chunk_max_size
+      return ActiveStorage.streaming_chunk_max_size if ActiveStorage.respond_to?(:streaming_chunk_max_size)
+
+      100 * 1024 * 1024
     end
   end
 end

data/app/controllers/livechat/visitor_controller.rb

@@ -90,7 +90,7 @@ module Livechat
         visitor_token: current_visitor_id ? visitor_token : ensure_visitor_token,
         visitor_label: visitor_label,
         visitor_email: (current_visitor.try(:email).presence if current_visitor),
-        page_url: params[:page_url].to_s.first(255).presence,
+        page_url: clean_page_url(params[:page_url]),
         locale: params[:locale].to_s.first(10).presence
       )
     end
@@ -105,7 +105,8 @@ module Livechat
     # "where are they stuck right now" is what an answering agent needs.
     def refresh_context(conversation)
       updates = {}
-      updates[:page_url] = params[:page_url].to_s.first(255) if params[:page_url].present?
+      page_url = clean_page_url(params[:page_url])
+      updates[:page_url] = page_url if page_url
       updates[:locale] = params[:locale].to_s.first(10) if params[:locale].present?
       conversation.update_columns(updates) if updates.any?
     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/app/models/livechat/conversation.rb

@@ -19,6 +19,20 @@ module Livechat
 
     scope :recent_first, -> { order(last_activity_at: :desc, id: :desc) }
 
+    # Host-controlled retention. Only resolved threads whose last activity is
+    # older than the supplied cutoff are removed; open conversations are never
+    # deleted automatically. Destroying (rather than delete_all) lets Rails run
+    # the message and Active Storage attachment lifecycle. Returns the number
+    # of conversations destroyed so a scheduled job can report what it did.
+    def self.purge_resolved(older_than:)
+      destroyed = 0
+      where(status: 'resolved', last_activity_at: ...older_than).find_each do |conversation|
+        conversation.destroy!
+        destroyed += 1
+      end
+      destroyed
+    end
+
     STATUSES.each do |status|
       define_method(:"#{status}?") { self.status == status }
     end

data/app/models/livechat/message.rb

@@ -108,8 +108,8 @@ module Livechat
         { id: file.id,
           name: file.filename.to_s,
           url: "#{base}/attachments/#{file.id}",
-          image: content_type.start_with?('image/'),
-          audio: content_type.start_with?('audio/'),
+          image: AttachmentPolicy.image?(content_type),
+          audio: AttachmentPolicy.audio?(content_type),
           size: file.byte_size }
       end
     end

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/attachment_policy.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Livechat
+  # The small set of uploads the engine renders in a browser instead of
+  # downloading. Active Storage owns the safe image/PDF allowlist; Livechat
+  # adds common audio formats because voice messages are a first-class feature.
+  module AttachmentPolicy
+    INLINE_AUDIO_TYPES = %w[
+      audio/mpeg audio/mp4 audio/ogg audio/wav audio/webm audio/x-wav
+    ].freeze
+
+    module_function
+
+    def inline?(content_type)
+      audio?(content_type) || ActiveStorage.content_types_allowed_inline.include?(content_type)
+    end
+
+    def image?(content_type)
+      content_type.to_s.start_with?('image/') &&
+        ActiveStorage.content_types_allowed_inline.include?(content_type)
+    end
+
+    def audio?(content_type)
+      INLINE_AUDIO_TYPES.include?(content_type)
+    end
+  end
+end

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 = '0.10.1'
+  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/{app/helpers → lib}/livechat/widget_helper.rb

@@ -1,11 +1,10 @@
 # frozen_string_literal: true
 
 module Livechat
-  # Included into the host's ActionView. Drop `<%= livechat_tag %>` before
-  # </body> in your layout; it renders nothing unless chat is enabled for the
-  # request. The widget shows a floating launcher (unless show_launcher is
-  # off) and also opens from any element carrying `data-livechat-open`, or
-  # from `window.Livechat.open()`.
+  # Included into the host's ActionView. Kept under lib and required before the
+  # engine registers its Action View load hook: a host initializer may load
+  # Action View before Rails sets up application autoloaders, when a helper
+  # living only under app/helpers is not yet a resolvable constant.
   module WidgetHelper
     def livechat_tag
       return unless Livechat.enabled?(request)
@@ -13,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
@@ -29,17 +28,11 @@ module Livechat
       data = (options.delete(:data) { {} } || {}).merge(livechat_open: '')
       data[:livechat_message] = message if message.present?
 
-      tag.button(label, type: 'button', data: data, **options)
+      tag.button(label, type: 'button', data:, **options)
     end
 
     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

@@ -3,6 +3,8 @@
 require 'livechat/version'
 require 'livechat/configuration'
 require 'livechat/widget'
+require 'livechat/widget_helper'
+require 'livechat/attachment_policy'
 require 'livechat/notifications'
 require 'livechat/seeds'
 require 'livechat/engine'
@@ -28,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: 0.10.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Yaroslav Shmarov
@@ -16,6 +16,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -23,6 +26,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
 description: |
   A mountable Rails engine that adds support chat to your app — the thing
   you'd otherwise pay Crisp or Intercom for, or deploy Chatwoot to get. A
@@ -43,6 +49,7 @@ files:
 - MIT-LICENSE
 - README.md
 - Rakefile
+- SECURITY.md
 - app/controllers/concerns/livechat/request_context.rb
 - app/controllers/livechat/application_controller.rb
 - app/controllers/livechat/attachments_controller.rb
@@ -52,7 +59,6 @@ files:
 - app/controllers/livechat/visitor_controller.rb
 - app/controllers/livechat/widgets_controller.rb
 - app/helpers/livechat/inbox_helper.rb
-- app/helpers/livechat/widget_helper.rb
 - app/mailers/livechat/mailer.rb
 - app/models/livechat/application_record.rb
 - app/models/livechat/conversation.rb
@@ -96,6 +102,7 @@ files:
 - lib/generators/livechat/install/templates/initializer.rb
 - lib/generators/livechat/migration_helpers.rb
 - lib/livechat.rb
+- lib/livechat/attachment_policy.rb
 - lib/livechat/channels.rb
 - lib/livechat/configuration.rb
 - lib/livechat/dashboard.css
@@ -106,13 +113,14 @@ files:
 - lib/livechat/version.rb
 - lib/livechat/widget.js
 - lib/livechat/widget.rb
+- lib/livechat/widget_helper.rb
 - lib/tasks/livechat_tasks.rake
 homepage: https://github.com/yshmarov/livechat
 licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/yshmarov/livechat
-  source_code_uri: https://github.com/yshmarov/livechat
+  source_code_uri: https://github.com/yshmarov/livechat/tree/main
   changelog_uri: https://github.com/yshmarov/livechat/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/yshmarov/livechat/issues
   rubygems_mfa_required: 'true'
@@ -130,7 +138,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+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.'