studio-engine 0.137.0 → 0.138.0

data/app/views/studio/integrations/index.html.erb

@@ -0,0 +1,22 @@
+<%# /admin/integrations: every integration the host enabled
+    (Studio.enable_integration), with its status and Connect
+    (Studio::IntegrationsController#index). %>
+<% content_for(:title, "Integrations") %>
+<div class="max-w-4xl mx-auto px-4 py-6" data-studio-integrations>
+  <%= render "studio/page_header", title: "Integrations" %>
+  <p class="text-sm text-secondary mt-1 mb-6">Connect an account once. Each integration's page shows its connections and what this app reads.</p>
+
+  <% if @integrations.empty? %>
+    <div class="empty-state">
+      <p class="text-heading font-semibold mb-1">No integrations enabled</p>
+      <p class="text-sm text-muted">Enable one with <code>Studio.enable_integration</code>; see the engine's docs/INTEGRATIONS.md.</p>
+    </div>
+  <% else %>
+    <div class="grid gap-4">
+      <% @integrations.each do |integration| %>
+        <%= render "studio/integrations/card", integration:, connections: integration.connections,
+                                               return_to: integrations_index_path, linked: true %>
+      <% end %>
+    </div>
+  <% end %>
+</div>

data/app/views/studio/integrations/show.html.erb

@@ -0,0 +1,24 @@
+<%# /admin/integrations/<key>: one enabled integration, its connections and
+    Disconnect, the redirect URI to register, and the host's own panel
+    (Studio.enable_integration panel:), rendered with locals integration: and
+    connections: (Studio::IntegrationsController#show). %>
+<% content_for(:title, @integration.label) %>
+<div class="max-w-4xl mx-auto px-4 py-6" data-studio-integration="<%= @integration.key %>">
+  <%= render "studio/page_header", title: @integration.label %>
+  <p class="text-sm mt-1 mb-6"><a href="<%= integrations_index_path %>" class="text-secondary hover:underline">All integrations</a></p>
+
+  <%= render "studio/integrations/card", integration: @integration, connections: @connections,
+                                         return_to: integration_path_for(@integration), linked: false %>
+
+  <div class="card p-4 mt-4" data-studio-integration-redirect>
+    <p class="label-upper mb-1">Redirect URI</p>
+    <p class="text-sm text-secondary mb-2">Register this exact URL on the <%= @integration.label %> app as its redirect (callback) URI.</p>
+    <code class="text-sm break-all"><%= integration_callback_url(@integration) %></code>
+  </div>
+
+  <% if @integration.panel %>
+    <div class="mt-6" data-studio-integration-panel>
+      <%= render partial: @integration.panel, locals: { integration: @integration, connections: @connections } %>
+    </div>
+  <% end %>
+</div>

data/app/views/style/_tricks.html.erb

@@ -267,6 +267,21 @@
         <% end %>
       </div>
     <% end %>
+
+    <%# The cascade: a 3D stack, five in view (visible: 3 shows one each side, and so
+        does a region under 36rem). Click a side card, drag, or use the arrow keys. %>
+    <%= render layout: "style/specimen", locals: { trick: "cascade" } do %>
+      <div class="w-full min-w-0" data-carousel-cascade-specimen>
+        <%= render layout: "studio/carousel",
+              locals: { label: "Cascade specimen", items: (1..7).to_a, style: :cascade, loop: true,
+                        id: "style-carousel-cascade-specimen", caption: ->(n) { "Slide #{n}" } } do |n| %>
+          <div class="card h-full p-5 space-y-1 aspect-[4/3]" style="background-image: linear-gradient(150deg, rgb(var(--color-primary-rgb) / 0.35), transparent)">
+            <p class="label-upper">Slide <%= n %></p>
+            <p class="text-sm text-body">Any block content.</p>
+          </div>
+        <% end %>
+      </div>
+    <% end %>
   </section>
 
   <!-- Surfaces, text and form -->

data/config/studio_tricks.yml

@@ -160,6 +160,13 @@ spotlight:
   note: "Centres one slide with its caption; its neighbours shrink and fade."
   resolve: [partial:studio/carousel, css:carousel-spotlight]
 
+cascade:
+  name: Cascade Carousel
+  group: Carousel
+  token: "render layout: \"studio/carousel\", style: :cascade"
+  note: "A 3D stack: the open slide in front, the others stepping back either side."
+  resolve: [partial:studio/carousel, css:carousel-cascade]
+
 card:
   name: Card
   group: "Surfaces, text & form"

data/db/migrate/20261006120001_ensure_error_logs_table.rb

@@ -14,7 +14,9 @@
 #     fail on existing rows or lock a large table.
 #
 # On every consumer that existed when this shipped, the second branch adds
-# nothing. Studio::HostSchema checks the same columns at boot.
+# nothing. Studio::HostSchema checks the same columns at boot. The slug
+# standard (NOT NULL, unique) is the later RequireSlugsOnEngineTables
+# (20261108160000), which tightens the column on every host.
 class EnsureErrorLogsTable < ActiveRecord::Migration[7.2]
   def up
     unless table_exists?(:error_logs)

data/db/migrate/20261006120002_ensure_theme_settings_table.rb

@@ -5,8 +5,9 @@
 # Sluggable, whose before_save writes `slug` on every save, and the setup doc's
 # hand-copied migration omitted it, so a theme save raises on any host built
 # from that doc (cyvasse, mcritchie-industries and moms-app when this shipped).
-# The slug is "theme-<app_name>", derived on save; existing rows keep a NULL
-# slug until their next save, and nothing looks a theme up by slug.
+# The slug is "theme-<app_name>", derived on save. Rows this left with a NULL
+# slug are filled, and the column made NOT NULL and unique, by the later
+# RequireSlugsOnEngineTables (20261108160000).
 #
 # A baseline, not a rebuild:
 #

data/db/migrate/20261108160000_require_slugs_on_engine_tables.rb

@@ -0,0 +1,119 @@
+# The engine's own settings and log tables take the hub's slug standard:
+# `slug` NOT NULL with a unique index, on error_logs, theme_settings,
+# studio_geo_settings and studio_site_identities (database audit 2026-11-07,
+# finding 6). Every host inherits the tables, so one migration reaches them all.
+#
+# Each table goes through three steps, and a table the host does not have is
+# skipped (its own create migration runs first whenever it is installed, since
+# install:migrations copies the engine's migrations in order):
+#
+#   1. Backfill. A NULL or blank slug gets the one its model would write
+#      (Sluggable's `name_slug`): `error-log-<id>`, `theme-<app_name>`,
+#      `geo-<app_name>`, `site-identity-<app_name>`, with the app name
+#      parameterized. A slug another row already holds takes `-<id>` after it.
+#   2. Duplicates. A table without a unique slug index (turf-monster's
+#      error_logs) may hold a slug twice; every copy after the lowest id takes
+#      `-<id>` after it. No table here has slug children, so nothing else
+#      references the old value.
+#   3. NOT NULL, then the unique index on `slug` unless one is there. A
+#      non-unique slug index is replaced by the unique one.
+#
+# Production on 2026-11-08 (every app with a database, read-only counts): no
+# NULL or blank slug, no duplicate, so steps 1 and 2 change no row there. The
+# largest table is the hub's error_logs at 606 rows, so the NOT NULL scan and
+# the index build are short. On Postgres each ALTER waits at most LOCK_TIMEOUT
+# for its lock; a migrate that cannot get it fails whole, changes nothing, and
+# runs again on the next release.
+class RequireSlugsOnEngineTables < ActiveRecord::Migration[7.2]
+  LOCK_TIMEOUT = "10s"
+
+  # table => the slug prefix its model's name_slug writes before the app name.
+  # error_logs has no app name: its slug is the id.
+  NAMED = {
+    "theme_settings" => "theme",
+    "studio_geo_settings" => "geo",
+    "studio_site_identities" => "site-identity"
+  }.freeze
+  TABLES = (["error_logs"] + NAMED.keys).freeze
+
+  def up
+    set_lock_timeout
+    TABLES.each do |table|
+      next unless table_exists?(table) && column_exists?(table, :slug)
+
+      backfill(table)
+      dedupe(table)
+      change_column_null table, :slug, false
+      unique_slug_index(table)
+    end
+  end
+
+  # Only the NOT NULL is undone. The unique index stays: most hosts had it before
+  # this migration, and a down cannot tell which index it added. Backfilled slugs
+  # stay too; a slug is a valid value either way.
+  def down
+    TABLES.each do |table|
+      next unless table_exists?(table) && column_exists?(table, :slug)
+
+      change_column_null table, :slug, true
+    end
+  end
+
+  private
+
+  def set_lock_timeout
+    return unless connection.adapter_name.downcase.include?("postgres")
+
+    execute "SET LOCAL lock_timeout = '#{LOCK_TIMEOUT}'"
+  end
+
+  def quoted(table) = connection.quote_table_name(table)
+
+  def backfill(table)
+    rows = connection.select_rows(<<~SQL.squish)
+      SELECT id#{', app_name' if NAMED.key?(table)} FROM #{quoted(table)}
+      WHERE slug IS NULL OR slug = '' ORDER BY id
+    SQL
+    rows.each do |id, app_name|
+      derived = derived_slug(table, id, app_name)
+      derived = "#{derived}-#{id}" if taken?(table, derived, id)
+      write_slug(table, id, derived)
+    end
+  end
+
+  def derived_slug(table, id, app_name)
+    return "error-log-#{id}" unless NAMED.key?(table)
+
+    name = ActiveSupport::Inflector.parameterize(app_name.to_s)
+    name.empty? ? "#{NAMED.fetch(table)}-#{id}" : "#{NAMED.fetch(table)}-#{name}"
+  end
+
+  def dedupe(table)
+    duplicates = connection.select_rows(<<~SQL.squish)
+      SELECT id, slug FROM #{quoted(table)} later
+      WHERE EXISTS (SELECT 1 FROM #{quoted(table)} earlier WHERE earlier.slug = later.slug AND earlier.id < later.id)
+      ORDER BY id
+    SQL
+    duplicates.each { |id, slug| write_slug(table, id, "#{slug}-#{id}") }
+  end
+
+  def taken?(table, slug, id)
+    connection.select_value(<<~SQL.squish).present?
+      SELECT 1 FROM #{quoted(table)} WHERE slug = #{connection.quote(slug)} AND id <> #{Integer(id)} LIMIT 1
+    SQL
+  end
+
+  def write_slug(table, id, slug)
+    connection.update(<<~SQL.squish, "#{self.class.name} backfill")
+      UPDATE #{quoted(table)} SET slug = #{connection.quote(slug)} WHERE id = #{Integer(id)}
+    SQL
+  end
+
+  def unique_slug_index(table)
+    slug_indexes = connection.indexes(table).select { |index| Array(index.columns) == ["slug"] }
+    return if slug_indexes.any?(&:unique)
+
+    slug_indexes.each { |index| remove_index table, name: index.name }
+    add_index table, :slug, unique: true
+  end
+end

data/db/migrate/20261108160001_add_engine_state_checks.rb

@@ -0,0 +1,94 @@
+# The engine's two state columns take the hub's state standard: a CHECK named
+# `<table>_<column>_known` holding the list the model validates against, so a
+# write that skips validations (update_columns, update_all, insert_all, raw SQL)
+# is refused by the database (database audit 2026-11-07, finding 6).
+#
+#   studio_links.kind             Studio::LinkToken::KINDS (Studio::Link validates it)
+#   studio_knowledge_docs.status  Studio::KnowledgeDoc::STATUSES
+#
+# The lists below are this migration's own frozen copy. A new value needs a new
+# migration: test/integration/engine_state_checks_test.rb fails while a model's
+# list and this copy differ.
+#
+# A host without the table is skipped, and a constraint already there is left
+# alone, so a second run changes nothing. Both columns are NOT NULL already.
+#
+# A row outside its list stops the migration before any change, with the table,
+# the column and the stray values in the message: the constraint is validated,
+# so it cannot go on over such a row. Production on 2026-11-08 held none (every
+# app with a database, read-only counts): studio_links holds magic_link and
+# referral, studio_knowledge_docs holds filed and superseded (industries alone).
+# The validating scan is short (the largest table is 366 rows). On Postgres the
+# ALTER waits at most LOCK_TIMEOUT for its lock; a migrate that cannot get it
+# fails whole and runs again on the next release.
+class AddEngineStateChecks < ActiveRecord::Migration[7.2]
+  LOCK_TIMEOUT = "10s"
+
+  CHECKS = {
+    "studio_links.kind" => %w[magic_link referral],
+    "studio_knowledge_docs.status" => %w[inbox filed superseded]
+  }.freeze
+
+  # The constraint's name: `<table>_<column>_known`, as the hub names its own.
+  def self.constraint_name(key) = key.tr(".", "_") + "_known"
+
+  def up
+    set_lock_timeout
+    CHECKS.each do |key, values|
+      table, column = key.split(".")
+      next unless table_exists?(table)
+      next if check_constraint_exists?(table, name: self.class.constraint_name(key))
+
+      refuse_strays!(table, column, values)
+      add_check_constraint table, expression(column, values), name: self.class.constraint_name(key)
+    end
+  end
+
+  def down
+    CHECKS.each_key do |key|
+      table, = key.split(".")
+      next unless table_exists?(table)
+
+      remove_check_constraint table, name: self.class.constraint_name(key), if_exists: true
+    end
+  end
+
+  private
+
+  def set_lock_timeout
+    return unless postgres?
+
+    execute "SET LOCAL lock_timeout = '#{LOCK_TIMEOUT}'"
+  end
+
+  def list(values) = values.map { |value| connection.quote(value) }.join(", ")
+
+  # On Postgres, the spelling Postgres itself settles on once a schema.rb is
+  # loaded (`'x'::character varying::text`), so a host's schema dump after this
+  # migrate equals the dump after a load, byte for byte. An `IN (...)` list
+  # dumps as `ARRAY[...]::text[]` first and changes on the next load. Anywhere
+  # else (the engine's SQLite test host), the plain IN list.
+  def expression(column, values)
+    col = connection.quote_column_name(column)
+    return "#{col} IN (#{list(values)})" unless postgres?
+
+    array = values.map { |value| "#{connection.quote(value)}::character varying::text" }.join(", ")
+    "(#{col})::text = ANY (ARRAY[#{array}])"
+  end
+
+  def postgres? = connection.adapter_name.downcase.include?("postgres")
+
+  def refuse_strays!(table, column, values)
+    col = connection.quote_column_name(column)
+    strays = connection.select_rows(<<~SQL.squish)
+      SELECT #{col}, COUNT(*) FROM #{connection.quote_table_name(table)}
+      WHERE #{col} IS NOT NULL AND #{col} NOT IN (#{list(values)}) GROUP BY #{col} ORDER BY #{col}
+    SQL
+    return if strays.empty?
+
+    found = strays.map { |value, count| "#{value.inspect} (#{count})" }.join(", ")
+    raise ActiveRecord::MigrationError,
+          "#{table}.#{column} holds values outside #{values.inspect}: #{found}. " \
+          "Resolve those rows, then migrate again."
+  end
+end

data/db/migrate/20261108170000_add_users_role_known_check.rb

@@ -0,0 +1,69 @@
+# CHECK users_role_known on the host's `users.role` (database audit 2026-11-07,
+# section 3): the database half of Studio::Account's role validation, so a
+# mistyped role is refused rather than saved as a quiet non-admin.
+#
+# THIS IS A MIGRATION AGAINST A HOST TABLE, shipped like the standard profile
+# columns (20260813220000): install-copied with
+# `bin/rails studio_engine:install:migrations`, never auto-run, and safe on an
+# app that already disagrees.
+#
+#   * No `users` table, no `role` column, or a role that is not a string (an
+#     integer enum): skipped.
+#   * A CHECK named users_role_known already there: skipped. The hub and Turf
+#     installed their own on 2026-11-08, narrowed to viewer + admin, and a host's
+#     narrower CHECK is the stronger guard; this one is the ceiling.
+#   * A row holding a role outside the list: REFUSED, naming the values, with
+#     nothing written. A stray role is a product call (Turf's "user" meant
+#     viewer); this migration does not guess it.
+#
+# Then it fills a NULL role with "viewer", sets NOT NULL, and adds the CHECK.
+#
+# The list is SPELLED OUT, not read from Studio::Roles: a migration is a record
+# that must still run years from now, and a live constant may move. Widening the
+# engine's list is a new migration that replaces this CHECK.
+class AddUsersRoleKnownCheck < ActiveRecord::Migration[7.2]
+  ROLES = %w[viewer member admin].freeze
+  NAME = "users_role_known"
+
+  def up
+    return unless string_role?
+    return if check_constraint_exists?(:users, name: NAME)
+
+    allowed = ROLES.map { |role| connection.quote(role) }.join(", ")
+    unknown = select_values("SELECT DISTINCT role FROM users WHERE role IS NOT NULL AND role NOT IN (#{allowed})")
+    if unknown.any?
+      raise ActiveRecord::MigrationError, <<~MSG
+        AddUsersRoleKnownCheck refused: users.role holds #{unknown.sort.map(&:inspect).join(', ')},
+        outside Studio::Roles (#{ROLES.join(', ')}). Move those rows to a known role in a
+        migration of this app's own (Turf moved "user" to "viewer"), then run this again.
+      MSG
+    end
+
+    execute "UPDATE users SET role = 'viewer' WHERE role IS NULL"
+    change_column_null :users, :role, false
+    add_check_constraint :users, "role IN (#{allowed})", name: NAME
+  end
+
+  # Removes the CHECK only when it is this migration's: one that names every
+  # engine role. A host's own users_role_known, which `up` left in place, is
+  # narrower (the hub's and Turf's name viewer and admin only) and stays. NOT
+  # NULL stays too: `up` cannot record whether the host had it already, and a
+  # NULL role is the one value no host wants back.
+  def down
+    return unless string_role?
+
+    ours = check_constraints(:users).find { |check| check.name == NAME }
+    return unless ours && ROLES.all? { |role| ours.expression.include?("'#{role}'") }
+
+    remove_check_constraint :users, name: NAME
+  end
+
+  private
+
+  def string_role?
+    return false unless table_exists?(:users)
+
+    column = columns(:users).find { |c| c.name == "role" }
+    column && %i[string text].include?(column.type)
+  end
+end

data/lib/generators/studio/connections/connections_generator.rb

@@ -53,6 +53,9 @@ module Studio
             bin/rails db:migrate
             Declare each provider in #{INITIALIZER}, then draw its routes in config/routes.rb:
               Studio.draw_connection_routes(self, :files, path: "admin/files", controller: "admin/files")
+            Or enable an integration the engine defines (docs/INTEGRATIONS.md) and mount its page:
+              Studio.enable_integration :quickbooks, env: { client_id: "INTUIT_CLIENT_ID", client_secret: "INTUIT_CLIENT_SECRET" }
+              Studio.draw_integrations_routes(self)
             Set the provider's client id and secret, and the app's Active Record encryption keys.
         TEXT
       end
@@ -68,6 +71,13 @@ module Studio
       INITIALIZER_BODY = <<~RUBY
         # frozen_string_literal: true
 
+        # Integrations the engine already defines (studio-engine docs/INTEGRATIONS.md):
+        # QuickBooks, Egnyte, Microsoft 365. One line each, naming this app's env
+        # vars; mount the page with Studio.draw_integrations_routes(self).
+        #
+        # Studio.enable_integration :quickbooks,
+        #   env: { client_id: "INTUIT_CLIENT_ID", client_secret: "INTUIT_CLIENT_SECRET", environment: "INTUIT_ENVIRONMENT" }
+        #
         # Connections (studio-engine docs/CONNECTIONS.md). One Studio.define_connection
         # per provider this app connects; each stays off until its client id and
         # secret are set. Draw its routes in config/routes.rb with

data/lib/studio/connections.rb

@@ -9,7 +9,7 @@ require "set"
 
 module Studio
   # CONNECTIONS: the generic tooling a host app uses to connect a third-party
-  # account over OAuth 2.0 (docs/CONNECTIONS.md). The engine knows no provider.
+  # account over OAuth 2.0 (docs/CONNECTIONS.md). The tooling knows no provider.
   # A host declares each one in an initializer, and the engine gives it:
   #
   #   * Studio::Connection, one table (studio_connections) holding one row per
@@ -30,7 +30,8 @@ module Studio
   #     account: :connect, account_param: "domain", account_format: /\A[a-z0-9-]{1,63}\z/
   #
   # Provider specifics (endpoints, scopes, quirks, readers, the admin page's
-  # live read) belong to the host. Nothing here is named after a vendor.
+  # live read) belong to the host. Nothing in this file is named after a vendor:
+  # the engine's own definitions live in Studio::Integrations (docs/INTEGRATIONS.md).
   module Connections
     # What reaching a provider can raise below HTTP: TLS, refused, timed out, DNS.
     NETWORK_ERRORS = [OpenSSL::SSL::SSLError, SocketError, SystemCallError, Net::OpenTimeout, Net::ReadTimeout].freeze
@@ -38,7 +39,18 @@ module Studio
     ENCRYPTION_ENV = %w[ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY
                         ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT].freeze
 
-    class Error < StandardError; end
+    # Every refusal below. A provider that names a trace_header (Intuit's
+    # intuit_tid) puts the answering call's trace id on the error: as #trace_id,
+    # and in the message, so the error log and the page carry it. Never a token.
+    class Error < StandardError
+      attr_reader :trace_header, :trace_id
+
+      def initialize(message = nil, trace_header: nil, trace_id: nil)
+        @trace_header = trace_header
+        @trace_id = trace_id.to_s.strip.presence
+        super(@trace_id && message ? "#{message} [#{@trace_header}: #{@trace_id}]" : message)
+      end
+    end
     # The provider's client id or secret is not set on this server.
     class NotConfigured < Error; end
     # The provider no longer honours the stored grant: revoked, expired, superseded.
@@ -175,7 +187,7 @@ module Studio
                   :revoke_format, :account_source, :account_param, :account_format, :private_account,
                   :authorize_params, :exchange_params, :rotation, :refresh_expires_in_key, :declined_errors,
                   :refusal_hint, :revoked_errors, :revoked_pattern, :rate_limited_statuses, :filter_keys,
-                  :revoke_note, :callback_check, :describe
+                  :revoke_note, :callback_check, :describe, :trace_header
 
       # Stand-in for the provider's token and revoke endpoints:
       # (url, form, headers) -> [status, body]. nil means the provider itself.
@@ -195,7 +207,7 @@ module Studio
                      rotation: nil, refresh_expires_in_key: nil, declined_errors: %w[access_denied],
                      refusal_hint: "Check the app's redirect URI, then start again.", revoked_errors: %w[invalid_grant],
                      revoked_pattern: nil, rate_limited_statuses: [429], filter_keys: [], revoke_note: nil,
-                     callback_check: nil, describe: nil)
+                     callback_check: nil, describe: nil, trace_header: nil)
         @key = key.to_s
         raise ArgumentError, "a connection key is lower-case letters, digits and underscores: #{@key.inspect}" unless @key.match?(/\A[a-z][a-z0-9_]*\z/)
 
@@ -240,6 +252,10 @@ module Studio
         @revoke_note = revoke_note || "Remove this app's access in #{@label} to revoke it there."
         @callback_check = callback_check
         @describe = describe
+        # A response header naming the call for the provider's support (Intuit:
+        # intuit_tid). Read from every token, refresh and revoke answer, logged
+        # with the call, kept as #last_trace_id and put on every error raised.
+        @trace_header = trace_header&.to_s
         @cache = {}
         @cache_lock = Mutex.new
       end
@@ -349,6 +365,27 @@ module Studio
         @cache_lock.synchronize { account ? @cache.delete(account.to_s.downcase) : @cache.clear }
       end
 
+      # The trace_header value of this thread's latest call to the provider, or nil.
+      def last_trace_id = (Thread.current[:studio_connection_traces] ||= {})[key]
+
+      # Reads trace_header from a response's headers (a Hash or a Net::HTTPResponse),
+      # remembers it as last_trace_id, and logs it with the call (no token, no body).
+      # Host readers call it on their own responses too.
+      def record_trace(headers, call:, status:)
+        return nil unless trace_header
+
+        value = case headers
+                when Hash then headers.find { |name, _| name.to_s.casecmp?(trace_header) }&.last
+                else headers.respond_to?(:[]) ? headers[trace_header] : nil
+                end
+        value = Array(value).first.to_s.strip.presence
+        (Thread.current[:studio_connection_traces] ||= {})[key] = value
+        if defined?(::Rails) && ::Rails.respond_to?(:logger) && ::Rails.logger
+          ::Rails.logger.info("[studio_connection] provider=#{key} call=#{call} status=#{status} #{trace_header}=#{value || '-'}")
+        end
+        value
+      end
+
       # How many accounts have a token cached in this process (:memory).
       def cached_count = @cache_lock.synchronize { @cache.size }
 
@@ -433,22 +470,24 @@ module Studio
         when :secret_only then form = form.merge(client_secret:)
         when :basic then headers["Authorization"] = "Basic #{Base64.strict_encode64("#{client_id}:#{client_secret}")}"
         end
-        status, body = call(url, form, headers)
+        status, body, answered = call(url, form, headers)
+        trace = record_trace(answered, call: form.key?(:token) ? "revoke" : form[:grant_type].to_s, status:)
         json = parse(body)
         # A revoke (allow_empty) is confirmed by any 2xx, a 204 included; a token answer must be a 200 with a body.
         return json if allow_empty ? (200..299).cover?(status) : (status == 200 && json.any?)
 
-        raise_for(status, json)
+        raise_for(status, json, trace)
       end
 
-      def raise_for(status, json)
+      def raise_for(status, json, trace = nil)
         detail = json["error_description"].to_s.lines.first.to_s.strip
         detail = (json["error"] || json["message"] || json["errorMessage"]).to_s if detail.empty?
         detail = "no detail" if detail.empty?
-        raise RateLimited, "#{label} is throttling this app (#{status}); try again in a few minutes" if rate_limited_statuses.include?(status)
-        raise Revoked, "#{label} no longer accepts this connection (#{detail}); connect again" if revoked?(status, json, detail)
+        traced = { trace_header:, trace_id: trace }
+        raise RateLimited.new("#{label} is throttling this app (#{status}); try again in a few minutes", **traced) if rate_limited_statuses.include?(status)
+        raise Revoked.new("#{label} no longer accepts this connection (#{detail}); connect again", **traced) if revoked?(status, json, detail)
 
-        raise Error, "#{label} answered #{status}: #{detail}"
+        raise Error.new("#{label} answered #{status}: #{detail}", **traced)
       end
 
       def revoked?(status, json, detail)
@@ -464,6 +503,8 @@ module Studio
         {}
       end
 
+      # [status, body, response headers]. A stand-in may answer [status, body]
+      # or [status, body, { "header" => "value" }].
       def call(url, form, headers)
         return http.call(url, form, headers) if http
 
@@ -474,7 +515,7 @@ module Studio
         headers.each { |name, value| request[name] = value }
         request.body = headers["Content-Type"] == "application/json" ? JSON.generate(form) : URI.encode_www_form(form)
         response = Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: 10, read_timeout: 20) { _1.request(request) }
-        [response.code.to_i, response.body]
+        [response.code.to_i, response.body, response]
       rescue *NETWORK_ERRORS => e
         raise Error, "#{label} could not be reached: #{e.class}"
       end

data/lib/studio/integrations/egnyte.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Studio
+  module Integrations
+    # EGNYTE, the connection only. A host's readers (folders, files) are its
+    # own; they call Studio.integration(:egnyte).api_base(connection).
+    #
+    #   * Every Egnyte domain answers on its own host, <domain>.egnyte.com, so
+    #     the admin types the domain at Connect (a POST, CSRF-checked). It is
+    #     normalized ("Acme", "acme.egnyte.com" and "https://acme.egnyte.com/"
+    #     are all "acme") and held to a DNS label before it reaches a URL.
+    #   * One scope, Egnyte.filesystem, on the authorize URL and the exchange.
+    #     The sign-in page and the token endpoint share one path.
+    #   * CACHED tokens: the access token lives 30 days and Egnyte asks callers
+    #     to cache it (its token endpoint allows about 100 requests an hour), so
+    #     the row keeps it and refreshes only within a day of its expiry or after
+    #     a 401. A refresh answers a new pair, stored before use.
+    #   * The revoke takes the token and the client secret, not the id.
+    #   * The token endpoint throttles with a 409 (and the API with a 429); an
+    #     "invalid refresh token" detail means the grant is gone.
+    #
+    # Checked against the hub's Egnyte::OAuthClient, EgnyteConnection and
+    # Egnyte::Reader (mcritchie-studio), which cite Egnyte's authentication docs.
+    module Egnyte
+      HOST_SUFFIX = ".egnyte.com"
+      TOKEN_PATH = "/puboauth/token"
+      REVOKE_PATH = "/pubapi/v1/tokens/revoke"
+      API_PATH = "/pubapi/v1"
+      SCOPE = "Egnyte.filesystem"
+      # A DNS label: what may stand before .egnyte.com. Nothing else reaches a URL.
+      DOMAIN = /\A[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\z/
+
+      def self.host(domain) = "https://#{domain}#{HOST_SUFFIX}"
+
+      # The bare domain from what an admin typed, lower-cased (still unchecked).
+      def self.normalize(value)
+        value.to_s.strip.downcase.sub(%r{\Ahttps?://}, "").sub(%r{[/?#].*\z}, "").delete_suffix(HOST_SUFFIX)
+      end
+
+      Integrations.register :egnyte,
+        label: "Egnyte",
+        summary: "An Egnyte domain's files, read with a user's own sign-in.",
+        connection: {
+          authorize_url: ->(domain) { "#{Egnyte.host(domain)}#{TOKEN_PATH}" },
+          token_url: ->(domain) { "#{Egnyte.host(domain)}#{TOKEN_PATH}" },
+          revoke_url: ->(domain) { "#{Egnyte.host(domain)}#{REVOKE_PATH}" },
+          scopes: [SCOPE], exchange_params: { scope: SCOPE },
+          client_auth: :form, revoke_auth: :secret_only,
+          refresh: :cached, refresh_margin: 1.day,
+          account: :connect, account_param: "egnyte_domain", account_format: DOMAIN,
+          normalize_account: ->(value) { Egnyte.normalize(value) },
+          rate_limited_statuses: [409, 429], revoked_pattern: /invalid refresh token|invalid_grant/i,
+          refusal_hint: "Check the developer key's redirect URI, then start again."
+        },
+        account_label: "Egnyte domain",
+        account_hint: "yourcompany (from yourcompany.egnyte.com)",
+        describe: lambda { |_integration, grant:, account:, get:|
+          token = grant["access_token"].to_s
+          next {} if token.empty?
+
+          username = get.call("#{Egnyte.host(account)}#{API_PATH}/whoami", token)["username"].to_s.strip
+          { metadata: username.empty? ? {} : { "username" => username } }
+        },
+        default_label: ->(domain) { "#{domain}#{HOST_SUFFIX}" },
+        api_base: ->(_integration, connection) { "#{Egnyte.host(connection.account_id)}#{API_PATH}" },
+        stand_in: { answer: { "username" => "stand-in" } }
+    end
+  end
+end