diff --git a/app/controllers/application_controller.rb b/app/controllers/application_controller.rb
index a52d12ee..db5c3e39 100644
--- a/app/controllers/application_controller.rb
+++ b/app/controllers/application_controller.rb
@@ -3,4 +3,13 @@ class ApplicationController < ActionController::Base
 
   # Only allow modern browsers supporting webp images, web push, badges, import maps, CSS nesting, and CSS :has.
   allow_browser versions: :modern
+
+  # Render-time half of the iframe embed allowlist: once a provider table is
+  # configured, `frame-src` is derived from the same table HtmlScrubber reads so
+  # the two can't drift. Left unset while permissive, so nothing that renders
+  # today is blocked, and only `frame-src` is set — the rest of the policy is
+  # deliberately unrestricted.
+  content_security_policy if: -> { EmbedProvider.configured? } do |policy|
+    policy.frame_src(*EmbedProvider.csp_frame_sources)
+  end
 end
diff --git a/app/models/account.rb b/app/models/account.rb
index 75802c75..4807e1fb 100644
--- a/app/models/account.rb
+++ b/app/models/account.rb
@@ -1,3 +1,8 @@
 class Account < ApplicationRecord
   include Joinable
+
+  # The iframe embed allowlist for this install, as EmbedProvider config entries.
+  # Nil leaves embeds permissive; FirstRun seeds the curated defaults for new
+  # installs, and an install upgraded from before the column keeps nil.
+  serialize :embed_providers, coder: JSON
 end
diff --git a/app/models/embed_provider.rb b/app/models/embed_provider.rb
new file mode 100644
index 00000000..2c364e3b
--- /dev/null
+++ b/app/models/embed_provider.rb
@@ -0,0 +1,254 @@
+# Which third-party <iframe> embeds are permitted in authored book content.
+#
+# The allowlist is opt-in. With nothing configured, embeds stay permissive:
+# HtmlScrubber keeps an <iframe> from any origin (attributes still scrubbed) and
+# no Content-Security-Policy is sent. Once a provider table is configured, both
+# enforcement points read from it so they can't drift:
+#
+#   * author-time  — HtmlScrubber keeps an <iframe> only when its src matches a
+#                    provider's host *and* path shape, and strips every attribute
+#                    the provider doesn't permit.
+#   * render-time  — a `frame-src` directive derived from the same table (see
+#                    ApplicationController).
+#
+# The table comes from, in order of precedence:
+#
+#   1. WRITEBOOK_EMBED_PROVIDERS — a JSON array of entries; the operator's
+#      per-install config, and the way an existing install opts in.
+#   2. Account#embed_providers — the same entries, stored per install. FirstRun
+#      seeds DEFAULTS here, so a new install starts on the curated list while an
+#      install upgraded from before the setting keeps embeds as they were.
+#   3. Neither — permissive.
+#
+# Whichever source applies is the whole table. There is no raw-iframe escape
+# hatch once configured: an embed is permitted only if a provider vouches for it.
+class EmbedProvider
+  # The widest set of attributes any provider may carry through the scrubber.
+  # Deliberately excludes srcdoc, sandbox, name and any on* handler (script /
+  # frame-busting), style (CSS exfil + overlay clickjacking), and allow /
+  # referrerpolicy (delegating powerful features or leaking the full URL to the
+  # embed) — so no configured provider can reintroduce them. Embeds are sized
+  # with width/height and go fullscreen with allowfullscreen; nothing here
+  # carries an author-controlled value that needs further sanitizing (src is
+  # validated by host + path below).
+  PERMITTED_ATTRIBUTES = %w[
+    src width height allowfullscreen frameborder title loading
+  ].freeze
+
+  # A DNS hostname: one or more [a-z0-9-] labels joined by dots, ending in an
+  # alphabetic-initial TLD label — no wildcard, no whitespace, and no IP literal.
+  # Requiring an alphabetic final label rejects IPv4 spellings (127.1,
+  # 2130706433, 0x7f.1, 0177.0.0.1) that Ruby parses but browsers canonicalize
+  # differently than the CSP source this table emits — which would otherwise let
+  # the scrubber keep a frame the CSP blocks. Guards operator config so a bad
+  # host can't widen (or, with embedded whitespace, crash) the derived directive.
+  HOST_FORMAT = /\A(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z](?:[a-z0-9-]*[a-z0-9])?\z/
+
+  # The curated table a new install starts with — the common authoring cases,
+  # each pinned to its approved path shape. In config-entry form, so it is also
+  # the value an existing install sets to opt in to the same list.
+  DEFAULTS = [
+    {
+      "name" => "YouTube",
+      "hosts" => %w[youtube.com www.youtube.com youtube-nocookie.com www.youtube-nocookie.com],
+      "path_prefix" => "/embed"
+    },
+    {
+      "name" => "Vimeo",
+      "hosts" => %w[player.vimeo.com],
+      "path_prefix" => "/video"
+    },
+    {
+      "name" => "Loom",
+      "hosts" => %w[loom.com www.loom.com],
+      "path_prefix" => "/embed"
+    },
+    {
+      "name" => "Google Maps",
+      "hosts" => %w[google.com www.google.com],
+      "path_prefix" => "/maps/embed"
+    }
+  ].freeze
+
+  Resolution = Struct.new(:source, :entries, :providers)
+
+  class << self
+    # True once a provider table is configured — by environment or by the
+    # account — and the allowlist is enforced. False leaves embeds permissive.
+    def configured?
+      !resolution.entries.nil?
+    end
+
+    def all
+      resolution.providers
+    end
+
+    # The provider vouching for +src+, or nil. Used by the scrubber both to decide
+    # whether to keep the <iframe> and to learn which attributes it may retain.
+    def match(src)
+      return if src.blank?
+
+      uri = parse(src)
+      return unless uri
+
+      all.find { |provider| provider.allows?(uri) }
+    end
+
+    def allows?(src)
+      !match(src).nil?
+    end
+
+    # CSP `frame-src` sources derived from the same table, or nil when
+    # permissive (no directive is sent). Host granularity here (implicit :443,
+    # matching the port the scrubber requires); path-shape enforcement lives in
+    # the scrubber. Always https. A configured table with no valid entry fails
+    # closed.
+    def csp_frame_sources
+      if configured?
+        all.flat_map(&:csp_sources).uniq.presence || [ :none ]
+      end
+    end
+
+    # Fragment cache keys wrapping scrubbed content include this: a cached
+    # fragment skips the scrubber, so it must be invalidated whenever the policy
+    # that produced it changes — permissive to configured, or an edit to the
+    # table. Digested in resolution order because match is first-match-wins:
+    # reordering overlapping entries changes the policy.
+    def cache_version
+      if configured?
+        ActiveSupport::Digest.hexdigest all.map(&:signature).join("\n")
+      else
+        "permissive"
+      end
+    end
+
+    # Parses +src+ into a URI only when it is a fetchable https URL, on the
+    # default port, with a host and no embedded userinfo (which would let
+    # "https://youtube.com@evil.com/…" read as trusted). Anything else —
+    # protocol-relative, data:, javascript:, http:, an explicit non-443 port,
+    # malformed — yields nil and is therefore never matched.
+    def parse(src)
+      uri = URI.parse(src.to_s.strip)
+      return unless uri.is_a?(URI::HTTPS)
+      return if uri.host.blank? || uri.userinfo.present?
+      return if uri.port != uri.default_port
+
+      uri
+    rescue URI::InvalidURIError
+      nil
+    end
+
+    private
+      # Resolved once per distinct configuration: the scrubber, the CSP directive
+      # and the fragment cache key all consult the table several times per
+      # request, and a parse failure or a rejected entry should be logged once,
+      # not per call. A changed environment value or account row is a new
+      # source, so it is picked up on the next read without a restart.
+      def resolution
+        source = [ ENV["WRITEBOOK_EMBED_PROVIDERS"].presence, Account.first&.embed_providers ]
+        resolved = @resolution
+        resolved = @resolution = resolve(source) unless resolved&.source == source
+        resolved
+      end
+
+      def resolve(source)
+        raw, account_entries = source
+        entries = parse_environment(raw) || account_entries
+        Resolution.new(source, entries, build(entries)).freeze
+      end
+
+      def parse_environment(raw)
+        if raw
+          parsed = JSON.parse(raw)
+          parsed.is_a?(Array) ? parsed : [ parsed ]
+        end
+      rescue JSON::ParserError
+        Rails.logger.warn("[EmbedProvider] WRITEBOOK_EMBED_PROVIDERS is not valid JSON; ignoring")
+        nil
+      end
+
+      def build(entries)
+        Array(entries).filter_map { |entry| normalize_config(entry) }.map { |attributes| new(**attributes) }.freeze
+      end
+
+      def normalize_config(entry)
+        return unless entry.is_a?(Hash)
+
+        hosts = Array(entry["hosts"] || entry["host"]).map { |host| host.to_s.strip.downcase }
+        hosts = hosts.select { |host| host.match?(HOST_FORMAT) }
+        path_prefix = canonical_path_prefix(entry["path_prefix"])
+
+        if hosts.empty? || path_prefix.nil?
+          Rails.logger.warn("[EmbedProvider] ignoring invalid provider entry: #{entry.inspect}")
+          return
+        end
+
+        attributes = entry["attributes"]
+        {
+          name: entry["name"].to_s.presence || hosts.first,
+          hosts: hosts,
+          path_prefix: path_prefix,
+          attributes: attributes.nil? ? nil : Array(attributes).map(&:to_s)
+        }
+      end
+
+      # Canonical form of a configured prefix: leading slash, duplicate slashes
+      # collapsed, no trailing slash. Nil — the entry is dropped — for a dot
+      # segment or anything that reduces to the root: a browser resolves "/.",
+      # "/./" and "//" to "/", so storing them verbatim would turn the entry
+      # into a whole-host allowance.
+      def canonical_path_prefix(prefix)
+        prefix = prefix.to_s
+        segments = prefix.split("/").reject(&:empty?)
+
+        if prefix.start_with?("/") && segments.any? && (segments & %w[. ..]).empty?
+          "/#{segments.join("/")}"
+        end
+      end
+  end
+
+  attr_reader :name, :hosts, :path_prefix, :attributes
+
+  def initialize(name:, hosts:, path_prefix:, attributes: nil)
+    @name = name
+    @hosts = Array(hosts).map { |host| normalize_host(host) }
+    @path_prefix = path_prefix
+    # Intersect with the master list so no configured provider can widen the
+    # attribute surface beyond what the scrubber vets.
+    @attributes = (attributes || PERMITTED_ATTRIBUTES) & PERMITTED_ATTRIBUTES
+  end
+
+  def allows?(uri)
+    hosts.include?(normalize_host(uri.host)) && path_allowed?(uri.path)
+  end
+
+  def csp_sources
+    hosts.map { |host| "https://#{host}" }
+  end
+
+  def signature
+    [ hosts, path_prefix, attributes ].to_json
+  end
+
+  private
+    # Case-insensitive only. A trailing dot is *not* stripped: "youtube.com." is a
+    # distinct hostname to a CSP `frame-src` source, so tolerating it here would let
+    # the scrubber keep a frame the CSP blocks. Left unmatched, it is rejected.
+    def normalize_host(host)
+      host.to_s.downcase
+    end
+
+    # Segment-boundary prefix match: "/embed" permits "/embed" and "/embed/<id>"
+    # but not "/embedded" or "/watch". Dot-segments and percent-encoded dot/slash
+    # are rejected outright so a path the browser would canonicalize past the
+    # prefix (e.g. "/embed/../watch") can't slip through.
+    def path_allowed?(path)
+      return false if path.blank? || traversal?(path)
+
+      path == path_prefix || path.start_with?("#{path_prefix}/")
+    end
+
+    def traversal?(path)
+      path.split("/").include?("..") || path.match?(/%2e|%2f/i)
+    end
+end
diff --git a/app/models/first_run.rb b/app/models/first_run.rb
index 574ea8fb..d6a892dc 100644
--- a/app/models/first_run.rb
+++ b/app/models/first_run.rb
@@ -2,7 +2,7 @@ class FirstRun
   ACCOUNT_NAME = "Writebook"
 
   def self.create!(user_params)
-    account = Account.create!(name: ACCOUNT_NAME)
+    account = Account.create!(name: ACCOUNT_NAME, embed_providers: EmbedProvider::DEFAULTS)
 
     User.create!(user_params.merge(role: :administrator)).tap do |user|
       DemoContent.create_manual(user)
diff --git a/app/models/html_scrubber.rb b/app/models/html_scrubber.rb
index ec237819..57d5a977 100644
--- a/app/models/html_scrubber.rb
+++ b/app/models/html_scrubber.rb
@@ -13,6 +13,15 @@ class HtmlScrubber < Rails::Html::PermitScrubber
     controls autoplay muted playsinline allowfullscreen frameborder loading open reversed
   ].freeze
 
+  # Bump whenever the scrubbing rules tighten. Fragment caches wrapping scrubbed
+  # content key on cache_version, so a fragment rendered under the old rules —
+  # or under a previous embed policy — is re-scrubbed rather than served verbatim.
+  POLICY_VERSION = 1
+
+  def self.cache_version
+    "#{POLICY_VERSION}-#{EmbedProvider.cache_version}"
+  end
+
   def initialize
     super
     self.tags = Rails::Html::WhiteListSanitizer.allowed_tags + %w[
@@ -33,6 +42,33 @@ def scrub(node)
     end
   end
 
+  # Once an embed allowlist is configured, an <iframe> survives only when an
+  # approved provider vouches for its src (host + path shape). Otherwise, and
+  # for every other tag, the default PermitScrubber behavior applies.
+  def keep_node?(node)
+    if node.name == "iframe" && EmbedProvider.configured?
+      EmbedProvider.allows?(node["src"])
+    else
+      super
+    end
+  end
+
+  # For a kept <iframe> under the allowlist, strip every attribute the matching
+  # provider doesn't permit — so srcdoc, sandbox, name, on* handlers, style, and
+  # allow/referrer policies can't ride along on an otherwise-approved embed. The
+  # surviving attributes carry no author-controlled URI or CSS value (src itself
+  # is validated by EmbedProvider), so no further per-value sanitizing is needed.
+  def scrub_attributes(node)
+    if node.name == "iframe" && EmbedProvider.configured?
+      permitted = EmbedProvider.match(node["src"])&.attributes || []
+      node.attribute_nodes.each do |attr|
+        node.remove_attribute(attr.name) unless permitted.include?(attr.name)
+      end
+    else
+      super
+    end
+  end
+
   # ARIA is a non-scriptable namespace Loofah allows by wildcard; keep it.
   def scrub_attribute?(name)
     return false if name.start_with?("aria-") || name == "role"
diff --git a/app/views/books/show.html.erb b/app/views/books/show.html.erb
index b90644d1..1de6a27c 100644
--- a/app/views/books/show.html.erb
+++ b/app/views/books/show.html.erb
@@ -49,7 +49,7 @@
   </nav>
 <% end %>
 
-<% cache [ @book, @book.editable? ] do %>
+<% cache [ @book, @book.editable?, HtmlScrubber.cache_version ] do %>
   <aside class="txt-align-center margin-block">
     <div class="book__sidebar <%= "theme--#{@book&.theme}" unless @book.cover.attached? %>">
       <% if @book.cover.attached? %>
diff --git a/app/views/leaves/_leaf.html.erb b/app/views/leaves/_leaf.html.erb
index e6282542..74b1e534 100644
--- a/app/views/leaves/_leaf.html.erb
+++ b/app/views/leaves/_leaf.html.erb
@@ -1,4 +1,4 @@
-<% cache [ leaf, leaf.book, leaf.book.editable? ] do %>
+<% cache [ leaf, leaf.book, leaf.book.editable?, HtmlScrubber.cache_version ] do %>
   <%= leaf_item_tag(leaf) do %>
     <span class="btn btn--link arrangement__handle txt-small">
       <%= image_tag "handle.svg", aria: { hidden: true }, size: 24 %>
diff --git a/db/migrate/20260909222120_add_embed_providers_to_accounts.rb b/db/migrate/20260909222120_add_embed_providers_to_accounts.rb
new file mode 100644
index 00000000..dd46eea9
--- /dev/null
+++ b/db/migrate/20260909222120_add_embed_providers_to_accounts.rb
@@ -0,0 +1,5 @@
+class AddEmbedProvidersToAccounts < ActiveRecord::Migration[8.2]
+  def change
+    add_column :accounts, :embed_providers, :text
+  end
+end
diff --git a/db/schema.rb b/db/schema.rb
index e0331993..d5280811 100644
--- a/db/schema.rb
+++ b/db/schema.rb
@@ -10,7 +10,7 @@
 #
 # It's strongly recommended that you check this file into your version control system.
 
-ActiveRecord::Schema[8.0].define(version: 2024_09_28_005927) do
+ActiveRecord::Schema[8.0].define(version: 2026_09_09_222120) do
   create_table "accesses", force: :cascade do |t|
     t.integer "user_id", null: false
     t.integer "book_id", null: false
@@ -28,6 +28,7 @@
     t.datetime "created_at", null: false
     t.datetime "updated_at", null: false
     t.text "custom_styles"
+    t.text "embed_providers"
   end
 
   create_table "action_text_markdowns", force: :cascade do |t|
diff --git a/test/controllers/books_controller_test.rb b/test/controllers/books_controller_test.rb
index 81d5f486..882a2df0 100644
--- a/test/controllers/books_controller_test.rb
+++ b/test/controllers/books_controller_test.rb
@@ -108,10 +108,54 @@ class BooksControllerTest < ActionDispatch::IntegrationTest
     assert_not_in_body "&lt;"
   end
 
+  test "show re-scrubs cached leaves when an allowlist is configured over permissive embeds" do
+    with_fragment_caching do
+      leaves(:welcome_page).leafable.update!(body: %(<iframe src="https://x.example/embed/1"></iframe>))
+
+      writes = 0
+      ActiveSupport::Notifications.subscribed(->(*) { writes += 1 }, "write_fragment.action_controller") do
+        get book_slug_path(books(:handbook))
+      end
+      assert_response :success
+      assert_select "iframe[src=?]", "https://x.example/embed/1"
+      assert_operator writes, :>, 0, "expected the page to be fragment cached"
+
+      ENV["WRITEBOOK_EMBED_PROVIDERS"] = EmbedProvider::DEFAULTS.to_json
+      get book_slug_path(books(:handbook))
+      assert_response :success
+      assert_select "iframe", count: 0
+    end
+  end
+
+  test "show re-scrubs cached leaves when the allowlist narrows" do
+    with_fragment_caching do
+      leaves(:welcome_page).leafable.update!(body: %(<iframe src="https://x.example/embed/1"></iframe>))
+
+      ENV["WRITEBOOK_EMBED_PROVIDERS"] = %([{"hosts":["x.example"],"path_prefix":"/embed"}])
+      get book_slug_path(books(:handbook))
+      assert_select "iframe[src=?]", "https://x.example/embed/1"
+
+      ENV["WRITEBOOK_EMBED_PROVIDERS"] = EmbedProvider::DEFAULTS.to_json
+      get book_slug_path(books(:handbook))
+      assert_select "iframe", count: 0
+    end
+  end
+
   test "show includes link to markdown format" do
     get book_slug_path(books(:handbook))
 
     assert_response :success
     assert_select "link[rel=\"alternate\"][type=\"text/markdown\"][href=\"#{book_slug_path(books(:handbook), format: :md)}\"]"
   end
+
+  private
+    def with_fragment_caching
+      perform_caching, cache_store = ActionController::Base.perform_caching, ActionController::Base.cache_store
+      ActionController::Base.perform_caching = true
+      ActionController::Base.cache_store = :memory_store
+      yield
+    ensure
+      ActionController::Base.perform_caching = perform_caching
+      ActionController::Base.cache_store = cache_store
+    end
 end
diff --git a/test/controllers/pages_controller_test.rb b/test/controllers/pages_controller_test.rb
index 0b0ccec8..e33690b5 100644
--- a/test/controllers/pages_controller_test.rb
+++ b/test/controllers/pages_controller_test.rb
@@ -30,6 +30,25 @@ class PagesControllerTest < ActionDispatch::IntegrationTest
     assert_select "#test", html: %(<iframe src="http://example.com"></iframe>)
   end
 
+  test "show keeps an approved-provider iframe under a configured allowlist" do
+    ENV["WRITEBOOK_EMBED_PROVIDERS"] = EmbedProvider::DEFAULTS.to_json
+    leaves(:welcome_page).leafable.update!(body: %(<div id="test"><iframe src="https://www.youtube.com/embed/dQw4w9WgXcQ"></iframe></div>))
+
+    get leafable_path(leaves(:welcome_page))
+
+    assert_select "#test iframe[src=?]", "https://www.youtube.com/embed/dQw4w9WgXcQ"
+  end
+
+  test "show strips an off-allowlist iframe under a configured allowlist" do
+    ENV["WRITEBOOK_EMBED_PROVIDERS"] = EmbedProvider::DEFAULTS.to_json
+    leaves(:welcome_page).leafable.update!(body: %(<div id="test"><iframe src="http://example.com"></iframe></div>))
+
+    get leafable_path(leaves(:welcome_page))
+
+    assert_select "#test", html: ""
+    assert_select "#test iframe", count: 0
+  end
+
   test "show with tables in the markdown" do
     get leafable_path(sample_page_leaf(%(| name | food |\n| ---- | ---- |\n| Kevin | Pizza |)))
 
diff --git a/test/helpers/pages_helper_test.rb b/test/helpers/pages_helper_test.rb
new file mode 100644
index 00000000..583dbe49
--- /dev/null
+++ b/test/helpers/pages_helper_test.rb
@@ -0,0 +1,68 @@
+require "test_helper"
+
+class PagesHelperTest < ActionView::TestCase
+  test "sanitize_content keeps an iframe from any origin while embeds are permissive" do
+    html = %(<iframe src="https://anything.example/embed/x" allow="camera *" onload="alert(1)" allowfullscreen></iframe>)
+    result = sanitize_content(html)
+
+    assert_includes result, %(src="https://anything.example/embed/x")
+    assert_includes result, "allowfullscreen"
+    assert_not_includes result, "allow="
+    assert_not_includes result, "onload"
+  end
+
+  test "sanitize_content keeps an approved-provider iframe" do
+    with_allowlist do
+      html = %(<iframe src="https://www.youtube.com/embed/dQw4w9WgXcQ"></iframe>)
+      result = sanitize_content(html)
+
+      assert_includes result, "<iframe"
+      assert_includes result, %(src="https://www.youtube.com/embed/dQw4w9WgXcQ")
+    end
+  end
+
+  test "sanitize_content strips a disallowed-origin iframe" do
+    with_allowlist do
+      html = %(<iframe src="https://evil.example/embed/x"></iframe>)
+      assert_not_includes sanitize_content(html), "<iframe"
+    end
+  end
+
+  test "sanitize_content strips a valid host used with the wrong path shape" do
+    with_allowlist do
+      html = %(<iframe src="https://www.youtube.com/watch?v=dQw4w9WgXcQ"></iframe>)
+      assert_not_includes sanitize_content(html), "<iframe"
+    end
+  end
+
+  test "sanitize_content strips forbidden attributes from an approved iframe" do
+    with_allowlist do
+      html = %(<iframe src="https://player.vimeo.com/video/76979871" ) +
+             %(srcdoc="<script>alert(1)</script>" sandbox="" onload="alert(1)" name="x" ) +
+             %(style="position:fixed" allow="camera *" referrerpolicy="unsafe-url" ) +
+             %(width="640" allowfullscreen></iframe>)
+      result = sanitize_content(html)
+
+      assert_includes result, "<iframe"
+      # Match on the attribute name= form so "allow" doesn't false-hit allowfullscreen.
+      %w[srcdoc= sandbox= onload= name= style= allow= referrerpolicy=].each do |forbidden|
+        assert_not_includes result, forbidden
+      end
+      assert_includes result, %(width="640")
+      assert_includes result, "allowfullscreen"
+    end
+  end
+
+  test "sanitize_content strips a bare srcdoc iframe with no src" do
+    with_allowlist do
+      html = %(<iframe srcdoc="<script>alert(1)</script>"></iframe>)
+      assert_not_includes sanitize_content(html), "<iframe"
+    end
+  end
+
+  private
+    def with_allowlist
+      ENV["WRITEBOOK_EMBED_PROVIDERS"] = EmbedProvider::DEFAULTS.to_json
+      yield
+    end
+end
diff --git a/test/integration/content_security_policy_test.rb b/test/integration/content_security_policy_test.rb
new file mode 100644
index 00000000..a98b66cf
--- /dev/null
+++ b/test/integration/content_security_policy_test.rb
@@ -0,0 +1,44 @@
+require "test_helper"
+
+class ContentSecurityPolicyTest < ActionDispatch::IntegrationTest
+  test "no policy is sent while embeds are permissive" do
+    get new_session_path
+    assert_response :success
+
+    assert_nil response.headers["Content-Security-Policy"]
+  end
+
+  test "frame-src carries the account's configured providers" do
+    accounts(:signal).update!(embed_providers: EmbedProvider::DEFAULTS)
+
+    assert_equal EmbedProvider.csp_frame_sources.sort, frame_src_tokens.sort
+  end
+
+  test "an environment-configured table reaches the header without a restart, replacing the account's" do
+    accounts(:signal).update!(embed_providers: EmbedProvider::DEFAULTS)
+    ENV["WRITEBOOK_EMBED_PROVIDERS"] =
+      %([{"name":"Wistia","hosts":["fast.wistia.net"],"path_prefix":"/embed/"}])
+
+    assert_equal %w[https://fast.wistia.net], frame_src_tokens
+  end
+
+  test "a configured table with no valid entry fails closed" do
+    ENV["WRITEBOOK_EMBED_PROVIDERS"] = %([{"hosts":["*"],"path_prefix":"/e"}])
+
+    assert_equal %w['none'], frame_src_tokens
+  end
+
+  private
+    def frame_src_tokens
+      get new_session_path
+      assert_response :success
+
+      csp = response.headers["Content-Security-Policy"]
+      assert csp.present?, "expected a Content-Security-Policy header"
+
+      frame_src = csp.split(";").map(&:strip).find { |directive| directive.start_with?("frame-src") }
+      assert frame_src.present?, "expected a frame-src directive, got: #{csp}"
+
+      frame_src.split(/\s+/).drop(1)
+    end
+end
diff --git a/test/models/embed_provider_test.rb b/test/models/embed_provider_test.rb
new file mode 100644
index 00000000..686935a6
--- /dev/null
+++ b/test/models/embed_provider_test.rb
@@ -0,0 +1,293 @@
+require "test_helper"
+
+class EmbedProviderTest < ActiveSupport::TestCase
+  setup { accounts(:signal).update!(embed_providers: EmbedProvider::DEFAULTS) }
+
+  # --- opt-in: permissive until a table is configured -----------------------
+
+  test "permissive when neither the environment nor the account configures a table" do
+    accounts(:signal).update!(embed_providers: nil)
+
+    assert_not EmbedProvider.configured?
+    assert_empty EmbedProvider.all
+    assert_nil EmbedProvider.csp_frame_sources
+    assert_equal "permissive", EmbedProvider.cache_version
+  end
+
+  test "permissive on an install with no account row at all" do
+    Account.delete_all
+
+    assert_not EmbedProvider.configured?
+    assert_nil EmbedProvider.csp_frame_sources
+  end
+
+  test "the account setting configures the allowlist" do
+    assert EmbedProvider.configured?
+    assert EmbedProvider.allows?("https://www.youtube.com/embed/abc")
+    assert_not EmbedProvider.allows?("https://evil.com/embed/abc")
+  end
+
+  test "the environment configures the allowlist on an install with no setting" do
+    accounts(:signal).update!(embed_providers: nil)
+    ENV["WRITEBOOK_EMBED_PROVIDERS"] = %([{"name":"Wistia","hosts":["fast.wistia.net"],"path_prefix":"/embed/"}])
+
+    assert EmbedProvider.configured?
+    assert EmbedProvider.allows?("https://fast.wistia.net/embed/iframe/abc")
+    assert_equal %w[https://fast.wistia.net], EmbedProvider.csp_frame_sources
+  end
+
+  test "the environment replaces the account setting rather than extending it" do
+    ENV["WRITEBOOK_EMBED_PROVIDERS"] = %([{"name":"Wistia","hosts":["fast.wistia.net"],"path_prefix":"/embed/"}])
+
+    assert EmbedProvider.allows?("https://fast.wistia.net/embed/iframe/abc")
+    assert_not EmbedProvider.allows?("https://www.youtube.com/embed/abc")
+    assert_equal %w[https://fast.wistia.net], EmbedProvider.csp_frame_sources
+  end
+
+  test "the curated defaults are config entries, so they round-trip through the environment" do
+    accounts(:signal).update!(embed_providers: nil)
+    ENV["WRITEBOOK_EMBED_PROVIDERS"] = EmbedProvider::DEFAULTS.to_json
+
+    assert EmbedProvider.allows?("https://www.youtube.com/embed/abc")
+    assert_equal EmbedProvider::DEFAULTS.flat_map { |entry| entry["hosts"].map { |host| "https://#{host}" } },
+      EmbedProvider.csp_frame_sources
+  end
+
+  # --- default providers: valid embeds pass ---------------------------------
+
+  {
+    "YouTube"          => "https://www.youtube.com/embed/dQw4w9WgXcQ",
+    "YouTube (nocookie)" => "https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ",
+    "Vimeo"            => "https://player.vimeo.com/video/76979871",
+    "Loom"             => "https://www.loom.com/embed/0123456789abcdef",
+    "Google Maps"      => "https://www.google.com/maps/embed?pb=!1m18!1m12!1m3"
+  }.each do |name, url|
+    test "#{name} embed is allowed" do
+      assert EmbedProvider.allows?(url), "expected #{url} to be allowed"
+    end
+  end
+
+  test "bare and www hosts both allowed" do
+    assert EmbedProvider.allows?("https://youtube.com/embed/abc")
+    assert EmbedProvider.allows?("https://www.youtube.com/embed/abc")
+  end
+
+  # --- disallowed origins ----------------------------------------------------
+
+  test "unknown origin is rejected" do
+    assert_not EmbedProvider.allows?("https://evil.com/embed/abc")
+  end
+
+  test "valid host with wrong path shape is rejected" do
+    assert_not EmbedProvider.allows?("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
+    assert_not EmbedProvider.allows?("https://player.vimeo.com/channels/staffpicks")
+    assert_not EmbedProvider.allows?("https://www.google.com/maps/place/foo")
+  end
+
+  # --- allowlist bypass attempts --------------------------------------------
+
+  test "path-prefix boundary tricks are rejected" do
+    assert_not EmbedProvider.allows?("https://www.youtube.com/embedxyz/evil")
+    assert_not EmbedProvider.allows?("https://www.youtube.com/embedded")
+  end
+
+  test "dot-segment and encoded traversal past the prefix are rejected" do
+    assert_not EmbedProvider.allows?("https://www.youtube.com/embed/../watch?v=x")
+    assert_not EmbedProvider.allows?("https://www.youtube.com/embed/%2e%2e/watch")
+    assert_not EmbedProvider.allows?("https://www.youtube.com/embed%2fx")
+  end
+
+  test "explicit non-default port is rejected (CSP is host-only, implicit 443)" do
+    assert_not EmbedProvider.allows?("https://www.youtube.com:444/embed/x")
+    assert EmbedProvider.allows?("https://www.youtube.com:443/embed/x")
+  end
+
+  test "protocol-relative url is rejected" do
+    assert_not EmbedProvider.allows?("//www.youtube.com/embed/abc")
+  end
+
+  test "non-https schemes are rejected" do
+    assert_not EmbedProvider.allows?("http://www.youtube.com/embed/abc")
+    assert_not EmbedProvider.allows?("data:text/html,<script>alert(1)</script>")
+    assert_not EmbedProvider.allows?("javascript:alert(1)")
+  end
+
+  test "userinfo host confusion is rejected" do
+    assert_not EmbedProvider.allows?("https://www.youtube.com@evil.com/embed/abc")
+    assert_not EmbedProvider.allows?("https://evil.com@www.youtube.com/embed/abc")
+  end
+
+  test "lookalike hostnames are rejected" do
+    assert_not EmbedProvider.allows?("https://notyoutube.com/embed/abc")
+    assert_not EmbedProvider.allows?("https://youtube.com.evil.com/embed/abc")
+  end
+
+  test "host is matched case-insensitively" do
+    assert EmbedProvider.allows?("https://WWW.YOUTUBE.COM/embed/abc")
+  end
+
+  test "trailing-dot host is rejected (CSP would not match it)" do
+    assert_not EmbedProvider.allows?("https://www.youtube.com./embed/abc")
+  end
+
+  test "blank and malformed srcs are rejected" do
+    assert_not EmbedProvider.allows?(nil)
+    assert_not EmbedProvider.allows?("")
+    assert_not EmbedProvider.allows?("https://")
+  end
+
+  # --- CSP frame-src derives from the same table ----------------------------
+
+  test "csp_frame_sources reflects exactly the configured table" do
+    assert_equal %w[
+      https://youtube.com https://www.youtube.com
+      https://youtube-nocookie.com https://www.youtube-nocookie.com
+      https://player.vimeo.com
+      https://loom.com https://www.loom.com
+      https://google.com https://www.google.com
+    ], EmbedProvider.csp_frame_sources
+  end
+
+  # --- config validation -----------------------------------------------------
+
+  test "default providers carry only the vetted attribute set" do
+    provider = EmbedProvider.match("https://www.youtube.com/embed/abc")
+    assert_equal EmbedProvider::PERMITTED_ATTRIBUTES, provider.attributes
+    %w[srcdoc sandbox name onload style allow referrerpolicy].each do |forbidden|
+      assert_not_includes provider.attributes, forbidden
+    end
+  end
+
+  test "config cannot reintroduce forbidden attributes" do
+    ENV["WRITEBOOK_EMBED_PROVIDERS"] =
+      %([{"name":"X","hosts":["x.example"],"path_prefix":"/e","attributes":["src","srcdoc","sandbox","onload","style","allow","referrerpolicy"]}])
+
+    provider = EmbedProvider.match("https://x.example/e/1")
+    assert_equal %w[src], provider.attributes
+  end
+
+  test "invalid environment json is ignored, the account setting still applies" do
+    ENV["WRITEBOOK_EMBED_PROVIDERS"] = "{not valid json"
+    assert EmbedProvider.allows?("https://www.youtube.com/embed/abc")
+    assert_not EmbedProvider.allows?("https://x.example/e/1")
+  end
+
+  test "a rejected entry or unparsable value is logged once per distinct configuration, not per call" do
+    ENV["WRITEBOOK_EMBED_PROVIDERS"] = %([{"name":"typo-#{SecureRandom.hex(4)}","hosts":["*"],"path_prefix":"/e"}])
+    log = capture_embed_provider_log do
+      3.times { EmbedProvider.all }
+      3.times { EmbedProvider.csp_frame_sources }
+    end
+    assert_equal 1, log.scan("ignoring invalid provider entry").size, log
+
+    ENV["WRITEBOOK_EMBED_PROVIDERS"] = "{not valid json #{SecureRandom.hex(4)}"
+    log = capture_embed_provider_log do
+      3.times { EmbedProvider.configured? }
+      3.times { EmbedProvider.all }
+    end
+    assert_equal 1, log.scan("not valid JSON").size, log
+  end
+
+  test "a changed configuration is picked up without a restart" do
+    ENV["WRITEBOOK_EMBED_PROVIDERS"] = %([{"hosts":["a.example"],"path_prefix":"/a"}])
+    assert EmbedProvider.allows?("https://a.example/a/1")
+
+    ENV["WRITEBOOK_EMBED_PROVIDERS"] = %([{"hosts":["b.example"],"path_prefix":"/b"}])
+    assert_not EmbedProvider.allows?("https://a.example/a/1")
+    assert EmbedProvider.allows?("https://b.example/b/1")
+
+    ENV.delete("WRITEBOOK_EMBED_PROVIDERS")
+    accounts(:signal).update!(embed_providers: [ { "hosts" => [ "c.example" ], "path_prefix" => "/c" } ])
+    assert EmbedProvider.allows?("https://c.example/c/1")
+    assert_not EmbedProvider.allows?("https://b.example/b/1")
+  end
+
+  test "a single provider object (not wrapped in an array) is accepted" do
+    ENV["WRITEBOOK_EMBED_PROVIDERS"] =
+      %({"name":"Wistia","hosts":["fast.wistia.net"],"path_prefix":"/embed/"})
+    assert EmbedProvider.allows?("https://fast.wistia.net/embed/iframe/abc")
+    assert_includes EmbedProvider.csp_frame_sources, "https://fast.wistia.net"
+  end
+
+  test "root-equivalent path prefixes are rejected and the table fails closed" do
+    %w[/ /. /./ // /embed/.. /embed/../ /embed/./.. embed].each do |prefix|
+      ENV["WRITEBOOK_EMBED_PROVIDERS"] = %([{"name":"x","hosts":["x.example"],"path_prefix":"#{prefix}"}])
+
+      assert EmbedProvider.configured?, prefix
+      assert_equal [ :none ], EmbedProvider.csp_frame_sources, prefix
+      assert_not EmbedProvider.allows?("https://x.example/anything"), prefix
+      assert_not EmbedProvider.allows?("https://x.example/./anything"), prefix
+      assert_not EmbedProvider.allows?("https://x.example//anything"), prefix
+    end
+  end
+
+  test "a configured path prefix is stored in canonical form" do
+    ENV["WRITEBOOK_EMBED_PROVIDERS"] = %([{"name":"x","hosts":["x.example"],"path_prefix":"/embed//x/"}])
+
+    provider = EmbedProvider.match("https://x.example/embed/x/1")
+    assert_equal "/embed/x", provider.path_prefix
+    assert_not EmbedProvider.allows?("https://x.example/embed/xy")
+    assert_not EmbedProvider.allows?("https://x.example/embed/../x/1")
+  end
+
+  test "wildcard, whitespace and over-broad config entries are rejected and the table fails closed" do
+    [
+      %([{"name":"a","hosts":["*"],"path_prefix":"/e"}]),
+      %([{"name":"b","hosts":["*.example.com"],"path_prefix":"/e"}]),
+      %([{"name":"c","hosts":["x.example bad"],"path_prefix":"/e"}]),
+      %([{"name":"d","hosts":["x.example"],"path_prefix":"/"}]),
+      %([{"name":"e","hosts":["127.1"],"path_prefix":"/e"}]),
+      %([{"name":"f","hosts":["0x7f.1"],"path_prefix":"/e"}])
+    ].each do |config|
+      ENV["WRITEBOOK_EMBED_PROVIDERS"] = config
+      # A fully-rejected entry leaves a configured but empty table — no wildcard,
+      # no whitespace, no IP-literal, and no path-prefix-of-"/" catch-all leaks
+      # in, and nothing falls back to a wider source.
+      assert_equal [ :none ], EmbedProvider.csp_frame_sources, config
+      assert_not EmbedProvider.allows?("https://x.example/anything"), config
+    end
+  end
+
+  # --- fragment cache version tracks the effective policy -------------------
+
+  test "cache_version distinguishes permissive from configured and follows the table" do
+    configured = EmbedProvider.cache_version
+    assert_equal configured, EmbedProvider.cache_version
+
+    accounts(:signal).update!(embed_providers: nil)
+    assert_equal "permissive", EmbedProvider.cache_version
+
+    ENV["WRITEBOOK_EMBED_PROVIDERS"] = %([{"name":"x","hosts":["x.example"],"path_prefix":"/e"}])
+    with_host = EmbedProvider.cache_version
+    assert_not_equal configured, with_host
+
+    ENV["WRITEBOOK_EMBED_PROVIDERS"] = %([{"name":"x","hosts":["x.example"],"path_prefix":"/e","attributes":["src"]}])
+    assert_not_equal with_host, EmbedProvider.cache_version
+
+    ENV["WRITEBOOK_EMBED_PROVIDERS"] = %([{"name":"x","hosts":["x.example"],"path_prefix":"/f"}])
+    assert_not_equal with_host, EmbedProvider.cache_version
+  end
+
+  test "cache_version follows resolution order, since match is first-match-wins" do
+    ENV["WRITEBOOK_EMBED_PROVIDERS"] =
+      %([{"hosts":["x.example"],"path_prefix":"/e","attributes":["src"]},{"hosts":["x.example"],"path_prefix":"/e"}])
+    narrow_first = EmbedProvider.cache_version
+    assert_equal %w[src], EmbedProvider.match("https://x.example/e/1").attributes
+
+    ENV["WRITEBOOK_EMBED_PROVIDERS"] =
+      %([{"hosts":["x.example"],"path_prefix":"/e"},{"hosts":["x.example"],"path_prefix":"/e","attributes":["src"]}])
+    assert_not_equal narrow_first, EmbedProvider.cache_version
+    assert_equal EmbedProvider::PERMITTED_ATTRIBUTES, EmbedProvider.match("https://x.example/e/1").attributes
+  end
+
+  private
+    def capture_embed_provider_log
+      log = StringIO.new
+      capture = ActiveSupport::Logger.new(log)
+      Rails.logger.broadcast_to(capture)
+      yield
+      log.string
+    ensure
+      Rails.logger.stop_broadcasting_to(capture)
+    end
+end
diff --git a/test/models/first_run_test.rb b/test/models/first_run_test.rb
index bd743e64..f72097ea 100644
--- a/test/models/first_run_test.rb
+++ b/test/models/first_run_test.rb
@@ -18,6 +18,22 @@ class FirstRunTest < ActiveSupport::TestCase
     end
   end
 
+  test "starts a new install on the curated embed providers" do
+    create_first_run_user
+
+    assert_equal EmbedProvider::DEFAULTS, Account.sole.embed_providers
+    assert EmbedProvider.configured?
+    assert EmbedProvider.allows?("https://www.youtube.com/embed/abc")
+    assert_not EmbedProvider.allows?("https://anything.example/embed/abc")
+  end
+
+  test "an install upgraded from before the setting stays permissive" do
+    Account.create!(name: "Upgraded")
+
+    assert_nil Account.sole.embed_providers
+    assert_not EmbedProvider.configured?
+  end
+
   test "creates a demo book" do
     assert_changes -> { Book.count }, to: 1 do
       create_first_run_user
diff --git a/test/models/html_scrubber_test.rb b/test/models/html_scrubber_test.rb
index af8c8711..605130bf 100644
--- a/test/models/html_scrubber_test.rb
+++ b/test/models/html_scrubber_test.rb
@@ -9,6 +9,30 @@ def render_and_scrub(markdown)
     scrub(ActionText::Markdown.renderer.call.render(markdown))
   end
 
+  test "cache_version changes when the embed policy does" do
+    permissive = HtmlScrubber.cache_version
+    assert_includes permissive, EmbedProvider.cache_version
+
+    ENV["WRITEBOOK_EMBED_PROVIDERS"] = %([{"hosts":["x.example"],"path_prefix":"/e"}])
+    assert_not_equal permissive, HtmlScrubber.cache_version
+  end
+
+  test "keeps an iframe from any origin while embeds are permissive, attributes still scrubbed" do
+    result = scrub(%(<iframe src="http://anything.example/x" srcdoc="<script>alert(1)</script>" onload="alert(1)" sandbox="" allowfullscreen></iframe>))
+    assert_includes result, %(<iframe src="http://anything.example/x")
+    assert_includes result, "allowfullscreen"
+    assert_not_includes result, "srcdoc"
+    assert_not_includes result, "onload"
+    assert_not_includes result, "sandbox"
+  end
+
+  test "keeps only approved-provider iframes once an allowlist is configured" do
+    ENV["WRITEBOOK_EMBED_PROVIDERS"] = EmbedProvider::DEFAULTS.to_json
+
+    assert_includes scrub(%(<iframe src="https://www.youtube.com/embed/abc"></iframe>)), "<iframe"
+    assert_not_includes scrub(%(<iframe src="https://anything.example/embed/abc"></iframe>)), "<iframe"
+  end
+
   test "strips inline event handlers on allowed tags" do
     %w[iframe img video audio details].each do |tag|
       result = scrub(%(<#{tag} onload="alert(1)" onerror="alert(1)"></#{tag}>))
@@ -79,7 +103,7 @@ def render_and_scrub(markdown)
   end
 
   test "strips value-sensitive iframe attributes but keeps safe embed attributes" do
-    result = scrub(%(<iframe src="https://ex.com" allow="camera" referrerpolicy="unsafe-url" sandbox="allow-scripts" allowfullscreen frameborder="0"></iframe>))
+    result = scrub(%(<iframe src="https://player.vimeo.com/video/76979871" allow="camera" referrerpolicy="unsafe-url" sandbox="allow-scripts" allowfullscreen frameborder="0"></iframe>))
     assert_not_includes result, "allow="
     assert_not_includes result, "referrerpolicy"
     assert_not_includes result, "sandbox"
diff --git a/test/test_helper.rb b/test/test_helper.rb
index 37e5e0a2..e3b9eb17 100644
--- a/test/test_helper.rb
+++ b/test/test_helper.rb
@@ -11,5 +11,10 @@ class TestCase
     fixtures :all
 
     include SessionTestHelper
+
+    # Tests assert against the shipped provider table, so a per-install
+    # WRITEBOOK_EMBED_PROVIDERS in the shell must not leak in — nor out.
+    setup { @embed_providers_before = ENV.delete("WRITEBOOK_EMBED_PROVIDERS") }
+    teardown { ENV["WRITEBOOK_EMBED_PROVIDERS"] = @embed_providers_before }
   end
 end