deacon-rails 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9b67729a41edf00bed6786b7b452d46280d312c38add74d0a8dba996c9110b2
-  data.tar.gz: 2424fcf30dc687f72f2438a837db3b90560eda33c6f8a89a22ace6c756a4e682
+  metadata.gz: da8d6aadcc7b35006f1a904adda812bafc11bd4ae63295547447e5d905b8acbd
+  data.tar.gz: 4f7075550ef183de2d723857692b7f52e97ed7f16036d406bc1556ae7db87241
 SHA512:
-  metadata.gz: d58bd949062b18345c26f8a706486d5deea5e9d5e956b36861113f9c8525fc5e9326bbb4199affd8a4b8ba0b4b61b03e87184648ae5db5f78b45fb799d0f1ed4
-  data.tar.gz: 992cd18343847745069d576eefc7443854c6d8117edfc568fd1a5a3fa08fa3632200d6626fd313c47b8984e35219bf0ea1c2a795e8e3defe79431e72e38d1b6e
+  metadata.gz: c6298ba5b22ba7d1e27f84f114213740492f39c1f823e7cfe4e9f9e6a63e1cd0f862231d316f10c3cf96ee44b816366b4fff377325dbdcca471b8c7f060dd077
+  data.tar.gz: 5706b3a17954523dea7b58e84dc141b7042e5911c2cd4f287603bec5925d2280eb16d3a247e3149ac7861067b4b9b9b42a0b33d2ce293662802b263a72ec9e74

data/README.md

@@ -40,31 +40,86 @@ Deacon only runs on the sites listed on Install. A listed domain covers its subd
 
 When you run `bin/rails server`, Install notices the widget on `localhost:3000` and lets you add it in one click. Chats on localhost don't count towards your plan.
 
-If you tell Deacon who is signed in, with the `window.deaconUser` script from [Deacon's install guide](https://heydeacon.com/agent/install.md), put that script above `<%= deacon_widget_tag %>` in the head, because the widget reads it as it starts.
+## Who is signed in
+
+When someone is signed in to your app, the tag tells Deacon their id, email and name, so their conversations show who they are. To have Deacon trust that, rather than take the page's word for it, give the gem your secret in the `DEACON_SECRET` environment variable:
+
+```sh
+DEACON_SECRET=deacon_identity_your_secret
+```
+
+To make one, open Install in Deacon and use Make a secret under Verify who's signed in. You see it once. The key the gem signs with is the whole string exactly as Install shows it, `deacon_identity_` and all, not decoded or shortened. Keep it on the server: unlike the `pk_` key, anyone who has it can tell Deacon they are any of your users.
+
+With the secret set, the gem does the rest:
+
+- Above the widget's tag it prints `window.deaconUser`, with the user's id, email and name and a `token` function.
+- When the chat opens, `token` posts to `/deacon/token`, a route the gem adds to your app. It answers with a token signed with `DEACON_SECRET` that names the user and this chat and lasts 10 minutes. With nobody signed in, or no secret, it answers 204 and signs nothing. Any other failure, such as a 404 or a 500, makes `token` throw, so Deacon can tell you the route is broken rather than take it for a sign-out. Its answers are never cached and carry no CORS headers, so only your own pages can read them.
+- On a page where nobody is signed in, it prints `window.deaconUser = null` and `Deacon.identify(null)` instead, so signing out ends what Deacon knew about the last person, and the next person on that computer starts fresh.
+
+If your layout sets `window.deaconUser` itself, from an earlier version of Deacon's install guide, take that script out: the tag prints it now.
+
+### Finding the user
+
+The gem asks your controllers for `current_user`, which Devise and most sign-in gems provide. Rails 8's built-in authentication has no `current_user`, so tell the gem how to find the user with a lambda, which runs inside the controller:
+
+```ruby
+Rails.application.config.deacon.current_user = -> { Current.user if authenticated? }
+```
+
+Or give it the name of a method, such as `:current_member`. The id it sends is the user's `id`, so it must name one person across your whole app. The email is the user's `email`, or `email_address` with Rails 8's built-in authentication, and the name is their `name`, when they have one.
+
+The token route's controller inherits your `ApplicationController`, so it finds the user just as your pages do. It skips `require_authentication` (Rails 8) and `authenticate_user!` (Devise), so someone who has signed out gets a 204 rather than a redirect to your sign-in page. If your `ApplicationController` requires sign-in under another name, skip that for the route too:
+
+```ruby
+Rails.application.config.to_prepare do
+  Deacon::Rails::TokensController.skip_before_action :require_login
+end
+```
+
+### CSRF
+
+The route checks your app's CSRF token, as every other POST in your app does, and the `token` function sends it in the `X-CSRF-Token` header. The route changes nothing, and with no CORS headers another site couldn't read its answer, so exempting it would be safe too. Keeping the check means a page on another site can't get your server to sign anything at all, and nothing in your app is exempt from it.
+
+### Staging and development
+
+Give staging its own Deacon team, with its own key and secret, or leave `DEACON_SECRET` unset there so the route answers 204. Never copy production's secret to staging or a laptop: whoever runs that server could sign a token for any of your users.
+
+### Signing in in the browser
+
+If your app learns who is signed in in the browser, such as a React front end on a JSON API, the server sees nobody on every page, and the sign-out line would start everyone afresh on every page load. Turn it off, and tell Deacon from your own code with `Deacon.identify`, as [Deacon's install guide](https://heydeacon.com/agent/install.md) shows:
+
+```ruby
+Rails.application.config.deacon.signed_in = false
+```
 
 ## Options
 
 Set them on `config.deacon`, in an initializer or in `config/application.rb`.
 
-| Option       | Type    | Default      | What it does |
-| ------------ | ------- | ------------ | ------------ |
-| `key`        | string  | `DEACON_KEY` | Your Deacon key. |
-| `context`    | hash    | none         | Details Deacon takes into account when it answers, the same on every page, such as `{ product: "api", docs_version: "3.2" }`. Up to 12 keys, each value a string, number or boolean. Anyone can read them in the page's HTML, so never put a secret here. |
-| `page_views` | boolean | `true`       | The same script counts visits for Deacon's website analytics. Set this to `false` to send no page views or JavaScript errors from your app. Chat still works. |
+| Option         | Type              | Default        | What it does |
+| -------------- | ----------------- | -------------- | ------------ |
+| `key`          | string            | `DEACON_KEY`   | Your Deacon key. |
+| `context`      | hash              | none           | Details Deacon takes into account when it answers, the same on every page, such as `{ product: "api", docs_version: "3.2" }`. Up to 12 keys, each value a string, number or boolean. Anyone can read them in the page's HTML, so never put a secret here. |
+| `page_views`   | boolean           | `true`         | The same script counts visits for Deacon's website analytics. Set this to `false` to send no page views or JavaScript errors from your app. Chat still works. |
+| `signed_in`    | boolean           | `true`         | Tell Deacon who is signed in, and sign them out of Deacon on pages where nobody is. Set this to `false` if your app signs people in in the browser. |
+| `current_user` | symbol or lambda  | `current_user` | How to find the signed-in user: the name of a method on your controllers, or a lambda that runs inside one. |
 
 ```ruby
 Rails.application.config.deacon.key = "pk_your_widget_key"
 Rails.application.config.deacon.context = { product: "api", docs_version: "3.2" }
 Rails.application.config.deacon.page_views = false
+Rails.application.config.deacon.current_user = -> { Current.user if authenticated? }
 ```
 
+The secret has no option, only `DEACON_SECRET`, so it stays out of your code.
+
 ## Turbo
 
-Turbo Drive swaps the `<body>` on each visit and keeps the `<head>`, so in the head the tag runs once. Deacon puts its chat on `<html>`, outside the body, so the widget stays in place as people move between pages.
+Turbo Drive swaps the `<body>` on each visit and keeps the `<head>`, so in the head the tag runs once. Deacon puts its chat on `<html>`, outside the body, so the widget stays in place as people move between pages. The signed-in script is different on every page, so Turbo runs it on each visit, and a sign-in or sign-out without a full page load still reaches Deacon.
 
 ## Content Security Policy
 
-If your app gives each request a nonce, with `config.content_security_policy_nonce_generator`, the tag carries it. The policy also needs Deacon's address, `https://heydeacon.com`, in `script-src`, `connect-src` and `frame-src`, and `'unsafe-inline'` in `style-src`, because the widget writes its styles where a nonce can't reach. Keep the nonce to `script-src`, since a nonce in `style-src` makes browsers ignore `'unsafe-inline'`:
+If your app gives each request a nonce, with `config.content_security_policy_nonce_generator`, the tag carries it, on the signed-in script too. With Turbo, also put `<%= csp_meta_tag %>` in the head, which Turbo reads to run the signed-in script again on each visit. The policy also needs Deacon's address, `https://heydeacon.com`, in `script-src`, `connect-src` and `frame-src`, and `'unsafe-inline'` in `style-src`, because the widget writes its styles where a nonce can't reach. Keep the nonce to `script-src`, since a nonce in `style-src` makes browsers ignore `'unsafe-inline'`:
 
 ```ruby
 Rails.application.configure do
@@ -92,7 +147,30 @@ The helper prints the same tag Install gives you:
 <script src="https://heydeacon.com/widget/v1/loader.js" data-key="pk_your_widget_key" async></script>
 ```
 
-It loads in the background without holding up the page. Works with Rails 8.0 and later, on Ruby 3.3 and later.
+It loads in the background without holding up the page. Above it, when someone is signed in, goes the signed-in script, here spread over lines:
+
+```html
+<script data-deacon-render="3f9c0a71d2e4b856">
+  window.deaconUser = {
+    id: "7",
+    email: "ana@studio.com",
+    name: "Ana Ruiz",
+    token: (nonce) => fetch("/deacon/token", {
+      method: "POST",
+      credentials: "same-origin",
+      headers: { "Content-Type": "application/json", "X-CSRF-Token": "…" },
+      body: JSON.stringify({ nonce }),
+    }).then((r) => {
+      if (r.status === 204) return "";
+      if (!r.ok) throw new Error("Deacon token route answered " + r.status);
+      return r.text();
+    }),
+  };
+  window.Deacon?.identify(window.deaconUser);
+</script>
+```
+
+Works with Rails 8.0 and later, on Ruby 3.3 and later.
 
 ## License
 

data/app/controllers/deacon/rails/tokens_controller.rb

@@ -0,0 +1,52 @@
+require "jwt"
+
+module Deacon
+  module Rails
+    # POST /deacon/token, which the page's token function calls when the chat opens: a token
+    # saying who is signed in, signed with DEACON_SECRET, for Deacon to check. It inherits the
+    # app's ApplicationController, so it finds the user as the app's own pages do and checks the
+    # CSRF token as every other POST in the app does.
+    class TokensController < ::ApplicationController
+      # How long a token lasts. Deacon refuses one that lasts more than 15 minutes.
+      LIFETIME = 10 * 60
+
+      # The widget session's nonce, which the token carries so it proves who is signed in to that
+      # session and no other. Deacon's are hex; anything far from that isn't one.
+      NONCE_FORMAT = /\A[A-Za-z0-9_-]{1,128}\z/
+
+      MISSING_SECRET = "deacon-rails: DEACON_SECRET is missing, so the token route signs nobody " \
+                       "and Deacon can't verify who is signed in. In Deacon, open Install (the " \
+                       "button at the top of the dashboard) and make a secret under Verify who's " \
+                       "signed in. It starts with deacon_identity_.".freeze
+
+      # The route answers for nobody signed in itself, with a 204, so the app's sign-in gates must
+      # not send that request to a sign-in page: Rails 8's built-in authentication's and Devise's.
+      skip_before_action :require_authentication, :authenticate_user!, raise: false
+
+      def create
+        # A token names one person, so no cache in front of the app may keep it for another.
+        response.headers["Cache-Control"] = "no-store, private"
+
+        nonce = request.request_parameters["nonce"]
+        return head(:bad_request) unless nonce.is_a?(String) && NONCE_FORMAT.match?(nonce)
+
+        user = CurrentUser.find(self)
+        return head(:no_content) unless user.is_a?(CurrentUser::Details)
+
+        # The key is the whole secret as Deacon showed it, deacon_identity_ and all.
+        secret = ENV["DEACON_SECRET"].to_s.strip
+
+        if secret.empty?
+          ::Rails.logger&.warn(MISSING_SECRET)
+          return head(:no_content)
+        end
+
+        now = Time.now.to_i
+        claims = { sub: user.id, email: user.email, name: user.name, nonce: nonce, iat: now,
+                   exp: now + LIFETIME }
+
+        render plain: JWT.encode(claims.compact, secret, "HS256")
+      end
+    end
+  end
+end

data/lib/deacon/rails/current_user.rb

@@ -0,0 +1,44 @@
+module Deacon
+  module Rails
+    # Who is signed in to the app, found the same way for the page and for the token route.
+    module CurrentUser
+      # The signed-in user as Deacon is told them: the id as a string, and the email and name
+      # when the user has them.
+      Details = Struct.new(:id, :email, :name)
+
+      # The signed-in user's Details, nil when nobody is signed in, or :unknown when the app has
+      # no way to say who is. config.deacon.current_user names a method on the controller, or is
+      # a lambda run inside it; without one, the controller's own current_user is used.
+      def self.find(controller)
+        lookup = ::Rails.application.config.deacon.current_user
+        lookup ||= :current_user if controller.respond_to?(:current_user, true)
+        return :unknown if lookup.nil?
+
+        user = case lookup
+               when Proc then controller.instance_exec(&lookup)
+               when Symbol, String then controller.send(lookup)
+               else
+                 raise ArgumentError, "deacon-rails: config.deacon.current_user must be a method " \
+                                      "name or a lambda."
+               end
+
+        details(user) if user
+      end
+
+      # Rails 8's built-in authentication names the address email_address. A user with no id,
+      # such as a guest object or one never saved, names nobody, so it counts as nobody.
+      def self.details(user)
+        id = user.id.to_s
+        return if id.empty?
+
+        email = if user.respond_to?(:email) then user.email
+                elsif user.respond_to?(:email_address) then user.email_address
+                end
+        name = user.name if user.respond_to?(:name)
+
+        Details.new(id, email.to_s.presence, name.to_s.presence)
+      end
+      private_class_method :details
+    end
+  end
+end

data/lib/deacon/rails/engine.rb

@@ -0,0 +1,25 @@
+module Deacon
+  module Rails
+    # What config.deacon holds. A Struct rather than ordered options, so a misspelt setting
+    # fails loudly at boot instead of being ignored.
+    Configuration = Struct.new(:key, :context, :page_views, :signed_in, :current_user)
+
+    # Adds config.deacon to the app, deacon_widget_tag to its views and POST /deacon/token to its
+    # routes. An engine rather than a plain Railtie, so the app loads the token route's
+    # controller with its own, after the ApplicationController it inherits.
+    class Engine < ::Rails::Engine
+      config.deacon = Configuration.new
+
+      initializer "deacon.view_helper" do
+        ActiveSupport.on_load(:action_view) { include Deacon::Rails::Helper }
+      end
+
+      # Ahead of the app's own routes, so a catch-all route of its own never answers instead.
+      initializer "deacon.token_route" do |app|
+        app.routes.prepend do
+          post "/deacon/token" => "deacon/rails/tokens#create", as: :deacon_token
+        end
+      end
+    end
+  end
+end

data/lib/deacon/rails/helper.rb

@@ -1,5 +1,6 @@
 require "erb"
 require "json"
+require "securerandom"
 
 module Deacon
   module Rails
@@ -25,18 +26,85 @@ module Deacon
 
         context = deacon_config.context
         page_views = deacon_config.page_views
+        signed_in = deacon_config.signed_in
         deacon_check_context(context)
-        deacon_check_page_views(page_views)
+        deacon_check_boolean(:page_views, page_views)
+        deacon_check_boolean(:signed_in, signed_in)
 
         attributes = { "data-key" => key }
         attributes["data-context"] = JSON.generate(context) unless context.nil?
         attributes["data-no-page-views"] = true if page_views == false
 
-        deacon_loader_tag(attributes, deacon_csp_nonce)
+        csp_nonce = deacon_csp_nonce
+        script = signed_in == false ? nil : deacon_signed_in_script(csp_nonce)
+
+        "#{script}#{deacon_loader_tag(attributes, csp_nonce)}".html_safe
       end
 
       private
 
+      # Who is signed in, for the loader to read as it starts, so it goes above the loader tag.
+      # The token function asks the app's own POST /deacon/token to sign them when the chat
+      # opens, sending the CSRF token as every other POST in the app does. With nobody signed
+      # in it signs the visitor out, so a sign-out ends Deacon's proof of who they were. An app
+      # with no way to say who is signed in gets neither.
+      def deacon_signed_in_script(csp_nonce)
+        user = CurrentUser.find(controller)
+        return if user == :unknown
+
+        code = if user.nil?
+                 "window.deaconUser = null; window.Deacon?.identify(null);"
+               else
+                 "window.deaconUser = #{deacon_user_object(user)}; " \
+                   "window.Deacon?.identify(window.deaconUser);"
+               end
+
+        deacon_script(code, csp_nonce)
+      end
+
+      # The user's id, email and name, and the token function: written as code rather than
+      # JSON, since a function has no JSON. A 204 is nobody signed in. Any other failure throws,
+      # so Deacon can tell the founder the route is broken instead of taking it for a sign-out.
+      def deacon_user_object(user)
+        headers = { "Content-Type" => "application/json" }
+        headers["X-CSRF-Token"] = form_authenticity_token if protect_against_forgery?
+        path = ::Rails.application.routes.url_helpers.deacon_token_path
+
+        token = "(nonce) => fetch(#{deacon_js(path)}, { method: \"POST\", " \
+                "credentials: \"same-origin\", headers: #{deacon_js_object(headers)}, " \
+                "body: JSON.stringify({ nonce }) })" \
+                '.then((r) => { if (r.status === 204) return ""; ' \
+                'if (!r.ok) throw new Error("Deacon token route answered " + r.status); ' \
+                "return r.text(); })"
+
+        fields = { id: user.id, email: user.email, name: user.name }.compact
+        fields = fields.map { |name, value| "#{name}: #{deacon_js(value)}" }
+
+        "{ #{[*fields, "token: #{token}"].join(', ')} }"
+      end
+
+      # A string as JavaScript, escaped so nothing in it can end the script it sits in.
+      def deacon_js(value)
+        ERB::Util.json_escape(JSON.generate(value.to_s))
+      end
+
+      def deacon_js_object(hash)
+        "{ #{hash.map { |name, value| "#{deacon_js(name)}: #{deacon_js(value)}" }.join(', ')} }"
+      end
+
+      # Turbo Drive keeps the head between visits and runs a script in the new page's head only
+      # when none just like it is there, so each page's is made unlike the last one's. Otherwise a
+      # sign-in or sign-out back to someone the head has seen before would never reach Deacon.
+      def deacon_script(code, csp_nonce)
+        render = SecureRandom.hex(8)
+
+        %(<script data-deacon-render="#{render}"#{deacon_nonce_attribute(csp_nonce)}>#{code}</script>)
+      end
+
+      def deacon_nonce_attribute(csp_nonce)
+        csp_nonce.nil? ? "" : %( nonce="#{ERB::Util.html_escape(csp_nonce)}")
+      end
+
       def deacon_config
         ::Rails.application.config.deacon
       end
@@ -56,10 +124,10 @@ module Deacon
                              "are strings, numbers or booleans."
       end
 
-      def deacon_check_page_views(page_views)
-        return if page_views.nil? || page_views == true || page_views == false
+      def deacon_check_boolean(name, value)
+        return if value.nil? || value == true || value == false
 
-        raise ArgumentError, "deacon-rails: config.deacon.page_views must be true or false."
+        raise ArgumentError, "deacon-rails: config.deacon.#{name} must be true or false."
       end
 
       def deacon_scalar?(value)
@@ -68,14 +136,13 @@ module Deacon
 
       # The tag Install gives, with any of its other attributes between the key and async, and
       # the nonce after them. An attribute that is true is written with no value, as async is.
-      def deacon_loader_tag(attributes, nonce)
+      def deacon_loader_tag(attributes, csp_nonce)
         rendered = attributes.map do |name, value|
           value == true ? " #{name}" : %( #{name}="#{ERB::Util.html_escape(value)}")
         end.join
 
-        nonce_attribute = nonce.nil? ? "" : %( nonce="#{ERB::Util.html_escape(nonce)}")
-
-        %(<script src="#{LOADER_SRC}"#{rendered} async#{nonce_attribute}></script>).html_safe
+        %(<script src="#{LOADER_SRC}"#{rendered} async#{deacon_nonce_attribute(csp_nonce)}></script>)
+          .html_safe
       end
     end
   end

data/lib/deacon/rails/version.rb

@@ -1,5 +1,5 @@
 module Deacon
   module Rails
-    VERSION = "1.0.0"
+    VERSION = "1.1.0"
   end
 end

data/lib/deacon/rails.rb

@@ -1,3 +1,4 @@
 require "deacon/rails/version"
+require "deacon/rails/current_user"
 require "deacon/rails/helper"
-require "deacon/rails/railtie" if defined?(::Rails::Railtie)
+require "deacon/rails/engine" if defined?(::Rails::Engine)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: deacon-rails
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Deacon
@@ -23,6 +23,26 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.8'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.8'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
 - !ruby/object:Gem::Dependency
   name: railties
   requirement: !ruby/object:Gem::Requirement
@@ -38,9 +58,10 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '8.0'
 description: A view helper, deacon_widget_tag, that puts the Deacon chat widget on
-  every page of a Rails app from one line in the layout. Deacon is an AI support agent
-  that answers questions from your own docs and content, and says when it doesn't
-  know.
+  every page of a Rails app from one line in the layout, and tells Deacon who is signed
+  in, with a token route that signs them with your secret so Deacon can trust it.
+  Deacon is an AI support agent that answers questions from your own docs and content,
+  and says when it doesn't know.
 email:
 - hello@heydeacon.com
 executables: []
@@ -49,9 +70,11 @@ extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
+- app/controllers/deacon/rails/tokens_controller.rb
 - lib/deacon/rails.rb
+- lib/deacon/rails/current_user.rb
+- lib/deacon/rails/engine.rb
 - lib/deacon/rails/helper.rb
-- lib/deacon/rails/railtie.rb
 - lib/deacon/rails/version.rb
 homepage: https://heydeacon.com
 licenses:

data/lib/deacon/rails/railtie.rb

@@ -1,16 +0,0 @@
-module Deacon
-  module Rails
-    # What config.deacon holds. A Struct rather than ordered options, so a misspelt setting
-    # fails loudly at boot instead of being ignored.
-    Configuration = Struct.new(:key, :context, :page_views)
-
-    # Adds config.deacon to the app and deacon_widget_tag to its views.
-    class Railtie < ::Rails::Railtie
-      config.deacon = Configuration.new
-
-      initializer "deacon.view_helper" do
-        ActiveSupport.on_load(:action_view) { include Deacon::Rails::Helper }
-      end
-    end
-  end
-end