mcp-auth 0.5.0 → 0.6.1

data/app/models/mcp/auth/oauth_client.rb

@@ -8,10 +8,41 @@ module Mcp
 
       # Set defaults BEFORE validation
       before_validation :set_defaults, on: :create
+      before_validation :sanitize_client_name
+      # Hash the secret at rest just before persisting (covers both the
+      # auto-generated secret and one a caller sets explicitly).
+      before_save :hash_client_secret_at_rest
+
+      # The grant/response types this authorization server actually implements.
+      # Dynamic registration is rejected for anything outside these sets so a
+      # client cannot register metadata the server can't honor (RFC 7591 §2).
+      SUPPORTED_GRANT_TYPES = %w[authorization_code refresh_token].freeze
+      SUPPORTED_RESPONSE_TYPES = %w[code].freeze
+
+      # Token-endpoint authentication methods (RFC 7591 / RFC 8414). PUBLIC_AUTH_METHOD
+      # (`none`) is a public client (PKCE only, no client authentication); the
+      # others are CONFIDENTIAL clients that MUST present a valid client_secret.
+      # Defaults to `none` so existing/registered clients keep working — a client
+      # opts into confidential auth explicitly at registration.
+      PUBLIC_AUTH_METHOD = 'none'
+      TOKEN_ENDPOINT_AUTH_METHODS = [PUBLIC_AUTH_METHOD, 'client_secret_basic', 'client_secret_post'].freeze
+
+      # Schemes that must never receive an authorization code: they execute
+      # script or read local content rather than reaching a client
+      # (e.g. `javascript://%0aalert(1)` would otherwise pass the `://` check).
+      FORBIDDEN_REDIRECT_SCHEMES = %w[javascript data vbscript file about blob].freeze
+
+      LOOPBACK_HOSTS = %w[localhost 127.0.0.1 [::1] ::1].freeze
+      MAX_CLIENT_NAME_LENGTH = 100
 
       validates :client_id, presence: true, uniqueness: true
       validates :client_secret, presence: true
+      validates :token_endpoint_auth_method, inclusion: { in: TOKEN_ENDPOINT_AUTH_METHODS }
       validate :validate_redirect_uris
+      validate :validate_grant_and_response_types
+      validate :validate_redirect_uri_policy
+      validate :validate_scope_known
+      validate :validate_client_uri
 
       serialize :redirect_uris, coder: JSON
       serialize :grant_types, coder: JSON
@@ -35,6 +66,11 @@ module Mcp
                primary_key: :client_id,
                dependent: :destroy
 
+      # The generated plaintext secret, available only on the in-memory instance
+      # right after creation (never persisted). The registration response returns
+      # this once; only its digest is stored.
+      attr_reader :plaintext_secret
+
       def self.find_by_client_id(client_id)
         find_by(client_id: client_id)
       end
@@ -47,14 +83,37 @@ module Mcp
         grant_types&.include?(grant_type)
       end
 
+      # Constant-time verification of a presented client_secret against the stored
+      # digest (secrets are hashed at rest).
+      def authenticate_secret(presented)
+        Mcp::Auth::SecretHashing.match?(client_secret, presented)
+      end
+
+      # Confidential clients MUST authenticate at the token endpoint; public
+      # clients (`none`) rely on PKCE.
+      def confidential?
+        token_endpoint_auth_method.to_s != PUBLIC_AUTH_METHOD
+      end
+
       private
 
       def set_defaults
         self.client_id ||= SecureRandom.uuid
-        self.client_secret ||= SecureRandom.hex(32)
+        self.client_secret = SecureRandom.hex(32) if client_secret.blank?
         self.grant_types ||= %w[authorization_code refresh_token]
         self.response_types ||= %w[code]
         self.scope ||= Mcp::Auth::ScopeRegistry.default_scope_string
+        self.token_endpoint_auth_method = PUBLIC_AUTH_METHOD if token_endpoint_auth_method.blank?
+      end
+
+      # Digest the secret before it is written. The plaintext (generated or
+      # caller-supplied) is captured on the in-memory instance first so the
+      # registration response can return it exactly once.
+      def hash_client_secret_at_rest
+        return if client_secret.blank? || Mcp::Auth::SecretHashing.hashed?(client_secret)
+
+        @plaintext_secret ||= client_secret
+        self.client_secret = Mcp::Auth::SecretHashing.digest(client_secret)
       end
 
       # RFC 7591 / RFC 8252: a client using the authorization_code grant must
@@ -62,11 +121,11 @@ module Mcp
       # We reject scheme-only values (e.g. `javascript:`/`data:`) that would be
       # XSS-redirect vectors, while still allowing http(s) and native app schemes.
       def validate_redirect_uris
-        return unless Array(grant_types).include?('authorization_code')
-
         uris = Array(redirect_uris)
         if uris.empty?
-          errors.add(:redirect_uris, 'must include at least one redirect URI')
+          if Array(grant_types).include?('authorization_code')
+            errors.add(:redirect_uris, 'must include at least one redirect URI')
+          end
           return
         end
 
@@ -75,8 +134,99 @@ module Mcp
         end
       end
 
+      def validate_grant_and_response_types
+        (Array(grant_types) - SUPPORTED_GRANT_TYPES).each do |gt|
+          errors.add(:grant_types, "contains an unsupported grant type: #{gt}")
+        end
+        (Array(response_types) - SUPPORTED_RESPONSE_TYPES).each do |rt|
+          errors.add(:response_types, "contains an unsupported response type: #{rt}")
+        end
+      end
+
+      # The consent page shows client_name, which is attacker-chosen at open
+      # registration: strip control/format characters (bidi overrides, zero-width)
+      # and cap the length so it can't impersonate or spoof layout.
+      def sanitize_client_name
+        return if client_name.blank?
+
+        self.client_name = client_name.to_s.gsub(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/, ' ').squish.truncate(MAX_CLIENT_NAME_LENGTH)
+      end
+
+      # OAuth 2.1 / RFC 9700 §4.1.1: redirect URIs must be https, or http only on
+      # a loopback host; and, when configured, must match the allowlist.
+      # Runs for EVERY registered redirect URI, whatever the grant types: a client
+      # registered without authorization_code must not be able to slip an
+      # off-policy URI past this check. (/oauth/authorize also refuses clients
+      # that didn't register the authorization_code grant.)
+      def validate_redirect_uri_policy
+        Array(redirect_uris).each do |uri|
+          next unless valid_redirect_uri_format?(uri) # already reported
+
+          parsed = URI.parse(uri.to_s)
+          loopback = loopback_redirect?(parsed)
+          if parsed.is_a?(URI::HTTP) && !parsed.is_a?(URI::HTTPS) && !loopback
+            errors.add(:redirect_uris, "must use https (http is only allowed for loopback): #{uri}")
+          elsif loopback && config_value(:allow_loopback_redirects, true) == false
+            errors.add(:redirect_uris, "loopback redirect URIs are not allowed: #{uri}")
+          elsif !loopback && !redirect_uri_allowlisted?(uri)
+            errors.add(:redirect_uris, "is not an allowed redirect URI: #{uri}")
+          end
+        end
+      end
+
+      def loopback_redirect?(parsed)
+        parsed.is_a?(URI::HTTP) && LOOPBACK_HOSTS.include?(parsed.host.to_s.downcase)
+      end
+
+      def redirect_uri_allowlisted?(uri)
+        patterns = config_value(:allowed_redirect_uri_patterns, nil)
+        return true if patterns.nil?
+
+        Array(patterns).any? { |pat| pat.is_a?(Regexp) ? full_match?(pat, uri.to_s) : pat.to_s == uri.to_s }
+      end
+
+      # A Regexp must match the WHOLE URI, even if the operator forgot \A/\z —
+      # otherwise %r{https://claude\.ai/cb} would accept
+      # https://evil.example/?x=https://claude.ai/cb.
+      def full_match?(pattern, string)
+        match = pattern.match(string)
+        !match.nil? && match.begin(0).zero? && match.end(0) == string.length
+      end
+
+      # Reject (strict) or narrow (non-strict) scopes the server doesn't know, so
+      # `*` / `admin` can't be registered and echoed back.
+      def validate_scope_known
+        return if scope.blank?
+
+        unknown = Mcp::Auth::ScopeRegistry.unknown_scopes(scope)
+        return if unknown.empty?
+
+        if config_value(:strict_scope_validation, true) != false
+          errors.add(:scope, "contains unsupported scope(s): #{unknown.join(' ')}")
+        else
+          self.scope = (scope.split - unknown).join(' ')
+        end
+      end
+
+      def validate_client_uri
+        return if client_uri.blank?
+
+        parsed = URI.parse(client_uri.to_s)
+        errors.add(:client_uri, 'must be an http(s) URL') unless parsed.is_a?(URI::HTTP) && parsed.host.present?
+      rescue URI::InvalidURIError
+        errors.add(:client_uri, 'must be an http(s) URL')
+      end
+
+      # Boolean settings are compared against an explicit `false` by the callers,
+      # so nil (unset) means the documented default — matching the controller.
+      def config_value(key, default)
+        config = Mcp::Auth.configuration
+        config.respond_to?(key) ? config.public_send(key) : default
+      end
+
       def valid_redirect_uri_format?(uri)
         parsed = URI.parse(uri.to_s)
+        return false if FORBIDDEN_REDIRECT_SCHEMES.include?(parsed.scheme.to_s.downcase)
         return true if parsed.is_a?(URI::HTTP) && parsed.host.present? # http(s) with host
         return true if parsed.scheme.present? && uri.to_s.include?('://') # native app scheme
 

data/app/models/mcp/auth/refresh_token.rb

@@ -13,17 +13,28 @@ module Mcp
                  primary_key: :client_id,
                  optional: true
 
+      # Plaintext token, available only in memory (never persisted); the `token`
+      # column stores the digest.
+      attr_accessor :plaintext_token
+
       validates :token, presence: true, uniqueness: true
       validates :client_id, presence: true
       validates :expires_at, presence: true
 
-      scope :active, -> { where('expires_at > ?', Time.current) }
+      # A token is "live" only if it is neither expired nor revoked. Rotation
+      # marks the presented token revoked (rather than deleting it) so that a
+      # later replay of the same token can be DETECTED as reuse.
+      scope :active, -> { where(revoked_at: nil).where('expires_at > ?', Time.current) }
       scope :expired, -> { where('expires_at <= ?', Time.current) }
 
       def expired?
         expires_at <= Time.current
       end
 
+      def revoked?
+        revoked_at.present?
+      end
+
       def self.cleanup_expired
         expired.delete_all
       end

data/app/views/mcp/auth/consent.html.erb

@@ -297,8 +297,21 @@
     <div class="client-info">
       <strong><%= @client_name %></strong>
       <p>wants to access your MCP server</p>
+      <p class="redirect-info">
+        You will be sent back to <strong><%= @redirect_host.presence || 'an unknown address' %></strong>
+      </p>
     </div>
 
+    <% unless @redirect_verified || @redirect_loopback %>
+    <div class="warning-box">
+      <div class="warning-icon">⚠️</div>
+      <div class="warning-text">
+        <strong>Unverified application.</strong> The name above was supplied by the application itself.
+        Only continue if you started this connection and recognize the address above.
+      </div>
+    </div>
+    <% end %>
+
     <% if @requested_scopes.any? { |s| s[:required] } %>
     <div class="warning-box">
       <div class="warning-icon">⚠️</div>

data/lib/generators/mcp/auth/hash_secrets_generator.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/active_record'
+
+module Mcp
+  module Auth
+    module Generators
+      # Step 2 of upgrading an existing install: copies the data migration that
+      # hashes secrets already stored in plaintext (client secrets, tokens, codes)
+      # to sha256$ digests, in place. Run it only after EVERY server runs a
+      # version that reads hashed rows (>= 0.6.0): older versions look secrets
+      # up by their plaintext and would reject every client and token.
+      # Irreversible. Safe to re-run the generator (an existing migration is
+      # skipped) and the migration (already-hashed rows are left alone).
+      #
+      #   rails generate mcp:auth:hash_secrets
+      #   rails db:migrate
+      class HashSecretsGenerator < Rails::Generators::Base
+        include ActiveRecord::Generators::Migration
+
+        source_root File.expand_path('templates', __dir__)
+
+        desc 'Adds the migration that hashes existing MCP Auth secrets at rest (run after every server is upgraded).'
+
+        def copy_hash_migration
+          migration_template 'hash_mcp_auth_secrets_at_rest.rb.erb',
+                             'db/migrate/hash_mcp_auth_secrets_at_rest.rb',
+                             migration_version: migration_version
+        end
+
+        def show_post_install_message
+          say "\nMCP Auth secrets-hashing migration added.", :green
+          say 'Only run it once NO server runs mcp-auth <= 0.5.0 (they cannot read hashed rows):'
+          say '  rails db:migrate'
+          say 'Irreversible: afterwards, rolling back to <= 0.5.0 signs every client out.'
+          say 'Then harden: config.secret_dual_read = false in config/initializers/mcp_auth.rb'
+        end
+
+        private
+
+        def migration_version
+          "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+        end
+      end
+    end
+  end
+end

data/lib/generators/mcp/auth/install_generator.rb

@@ -29,6 +29,18 @@ module Mcp
           migration_template "create_refresh_tokens.rb.erb",
                              "db/migrate/create_mcp_auth_refresh_tokens.rb",
                              migration_version: migration_version
+
+          # Hashes secrets at rest. On a fresh install this runs against empty
+          # tables (a no-op). Existing installs upgrade with mcp:auth:upgrade and,
+          # later, mcp:auth:hash_secrets instead of re-running this generator.
+          migration_template "hash_mcp_auth_secrets_at_rest.rb.erb",
+                             "db/migrate/hash_mcp_auth_secrets_at_rest.rb",
+                             migration_version: migration_version
+
+          # Confidential-client auth method + refresh-token reuse-detection columns.
+          migration_template "add_mcp_auth_confidential_client_and_reuse.rb.erb",
+                             "db/migrate/add_mcp_auth_confidential_client_and_reuse.rb",
+                             migration_version: migration_version
         end
 
         def copy_initializer
@@ -56,7 +68,7 @@ module Mcp
           say "MCP Auth has been installed!", :green
           say "="*80
           say "\nFiles created:"
-          say "  - db/migrate/*_create_mcp_auth_*.rb (4 migrations)"
+          say "  - db/migrate/*_mcp_auth_*.rb (6 migrations)"
           say "  - config/initializers/mcp_auth.rb"
           say "  - app/views/mcp/auth/consent.html.erb"
           say "\nNext steps:"

data/lib/generators/mcp/auth/templates/add_mcp_auth_confidential_client_and_reuse.rb.erb

@@ -0,0 +1,39 @@
+class AddMcpAuthConfidentialClientAndReuse < ActiveRecord::Migration<%= migration_version %>
+  # Adds columns for:
+  #   * confidential-client authentication — `token_endpoint_auth_method` on
+  #     clients. Existing rows default to 'none' (public / PKCE), so no already-
+  #     registered client is suddenly required to send a secret — a client opts
+  #     into confidential auth explicitly at (re-)registration.
+  #   * refresh-token reuse detection — `family_id` groups a rotation chain and
+  #     `revoked_at` marks a consumed token, so replaying a rotated token is
+  #     detected and the whole family is revoked.
+  def up
+    add_column :mcp_auth_oauth_clients, :token_endpoint_auth_method, :string,
+               null: false, default: 'none'
+
+    add_column :mcp_auth_refresh_tokens, :family_id, :string
+    add_column :mcp_auth_refresh_tokens, :revoked_at, :datetime
+    add_index  :mcp_auth_refresh_tokens, :family_id
+
+    # Backfill a distinct family per existing refresh token. Without this, legacy
+    # tokens keep family_id = NULL, and reuse detection can't revoke their family
+    # (revoke_refresh_family(nil) is a no-op) — so a token stolen before its first
+    # rotation couldn't cut off the successor. One family-per-token is correct:
+    # each pre-existing token is the root of its own future rotation chain.
+    say_with_time 'Backfilling refresh-token family_id' do
+      count = 0
+      select_all('SELECT id FROM mcp_auth_refresh_tokens WHERE family_id IS NULL').each do |row|
+        execute("UPDATE mcp_auth_refresh_tokens SET family_id = #{quote(SecureRandom.uuid)} WHERE id = #{quote(row['id'])}")
+        count += 1
+      end
+      count
+    end
+  end
+
+  def down
+    remove_index  :mcp_auth_refresh_tokens, :family_id
+    remove_column :mcp_auth_refresh_tokens, :revoked_at
+    remove_column :mcp_auth_refresh_tokens, :family_id
+    remove_column :mcp_auth_oauth_clients, :token_endpoint_auth_method
+  end
+end

data/lib/generators/mcp/auth/templates/hash_mcp_auth_secrets_at_rest.rb.erb

@@ -0,0 +1,72 @@
+class HashMcpAuthSecretsAtRest < ActiveRecord::Migration<%= migration_version %>
+  # Backfill: convert secrets already stored in PLAINTEXT to one-way digests.
+  #
+  # Why this is safe for EXISTING clients/tokens
+  # --------------------------------------------
+  # At migration time the plaintext is still present in each column, so we hash
+  # it IN PLACE. Nothing needs to be re-issued: a client keeps working because it
+  # still holds the original value (client_secret / refresh token / auth code)
+  # and presents it as before — the gem now re-hashes what is presented and
+  # matches it against the stored digest. Access-token JWTs are likewise matched
+  # by digest for the revocation lookup; the client keeps sending the full JWT.
+  #
+  # The `sha256$` prefix makes each digest self-identifying, which:
+  #   * makes this migration idempotent (a value already prefixed is skipped), and
+  #   * disambiguates a digest from a plaintext SecureRandom.hex(32) — both are
+  #     otherwise 64 hex characters.
+  #
+  # Hashing is done in Ruby (not a DB-specific SQL function) so it runs portably
+  # on SQLite, MySQL, and PostgreSQL.
+  #
+  # Irreversible by design.
+  PREFIX = 'sha256$'
+  BATCH_SIZE = 1000
+
+  def up
+    backfill_digest('mcp_auth_oauth_clients',       'client_secret', 'client_id')
+    backfill_digest('mcp_auth_access_tokens',       'token',         'id')
+    backfill_digest('mcp_auth_refresh_tokens',      'token',         'id')
+    backfill_digest('mcp_auth_authorization_codes', 'code',          'id')
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration,
+          'Secrets are stored as one-way hashes and cannot be restored to plaintext.'
+  end
+
+  private
+
+  def backfill_digest(table, column, pk)
+    return unless data_source_exists?(table) && column_exists?(table, column)
+
+    say_with_time "Hashing #{table}.#{column} at rest" do
+      updated = 0
+      each_batch(table, column, pk) do |row|
+        value = row['val']
+        next if value.blank? || value.to_s.start_with?(PREFIX)
+
+        digest = "#{PREFIX}#{Digest::SHA256.hexdigest(value.to_s)}"
+        execute("UPDATE #{table} SET #{column} = #{quote(digest)} WHERE #{pk} = #{quote(row['pk'])}")
+        updated += 1
+      end
+      updated
+    end
+  end
+
+  # Keyset-paginate by primary key so a large table (access tokens accumulate)
+  # is never loaded into memory at once. The pk is never modified, so the
+  # cursor is stable while rows are rewritten.
+  def each_batch(table, column, pk, &block)
+    last_pk = nil
+    loop do
+      where = last_pk.nil? ? '' : "WHERE #{pk} > #{quote(last_pk)}"
+      rows = select_all(
+        "SELECT #{pk} AS pk, #{column} AS val FROM #{table} #{where} ORDER BY #{pk} LIMIT #{BATCH_SIZE}"
+      ).to_a
+      break if rows.empty?
+
+      rows.each(&block)
+      last_pk = rows.last['pk']
+    end
+  end
+end

data/lib/generators/mcp/auth/templates/initializer.rb

@@ -5,15 +5,24 @@ Mcp::Auth.configure do |config|
   # OAUTH CONFIGURATION
   # ============================================================================
 
-  # OAuth secret for signing JWTs
-  # Should be a secure random string in production (use: rails secret)
-  config.oauth_secret = ENV.fetch('MCP_HMAC_SECRET', Rails.application.secret_key_base)
+  # OAuth secret for signing JWTs (HS256). REQUIRED outside development/test and
+  # must be DEDICATED — not Rails.application.secret_key_base, which also signs
+  # your cookies. Generate one with `rails secret`. (Dev/test fall back to
+  # secret_key_base when unset.) Not used with RS256/ES256 signing.
+  config.oauth_secret = ENV['MCP_HMAC_SECRET']
 
   # Authorization server URL (optional - defaults to same as resource server)
   # Set this if you're using a separate authorization server
   # Example: config.authorization_server_url = 'https://auth.example.com'
   config.authorization_server_url = ENV.fetch('MCP_AUTHORIZATION_SERVER_URL', nil)
 
+  # Public origin of the MCP resource server (optional - defaults to the request
+  # origin). The token audience, protected-resource metadata and 401 challenge
+  # are built from it. Set it to pin them against a forged Host header, and
+  # always set it when authorization_server_url points at a different host.
+  # Example: config.mcp_server_url = 'https://api.example.com'
+  config.mcp_server_url = ENV.fetch('MCP_SERVER_URL', nil)
+
   # ============================================================================
   # MCP SERVER CONFIGURATION
   # ============================================================================
@@ -40,6 +49,14 @@ Mcp::Auth.configure do |config|
   config.refresh_token_lifetime = 2_592_000     # 30 days
   config.authorization_code_lifetime = 1800     # 30 minutes
 
+  # Refresh-token rotation grace period (seconds). Refresh tokens rotate on every
+  # use and reuse is treated as theft (the whole token family is revoked). Real
+  # MCP clients often fire several refreshes at once when the access token
+  # expires, so a rotated token replayed WITHIN this window is treated as a benign
+  # race (rejected softly, family kept); a replay after it is treated as theft.
+  # Set to 0 to disable the grace and revoke on any replay.
+  config.refresh_token_reuse_grace_period = 10
+
   # ============================================================================
   # USER DATA FETCHER
   # ============================================================================
@@ -80,6 +97,32 @@ Mcp::Auth.configure do |config|
   config.current_user_method = :current_user
   config.current_org_method = :current_org
 
+  # ============================================================================
+  # DYNAMIC CLIENT REGISTRATION (DCR) POLICY
+  # ============================================================================
+
+  # /oauth/register is open (RFC 7591), so restrict where authorization codes can
+  # be sent. Plain http is always rejected except for loopback hosts.
+  #
+  # Restrict registration to known clients (Strings match exactly, Regexps must
+  # match the WHOLE URI, anchored or not; end a pattern with `.*` to allow any
+  # path, e.g. %r{https://app\.example\.com/.*}). nil = any https /
+  # native-scheme URI.
+  # config.allowed_redirect_uri_patterns = [
+  #   %r{\Ahttps://claude\.ai/api/mcp/auth_callback\z},
+  #   %r{\Ahttps://chatgpt\.com/connector_platform_oauth_redirect\z}
+  # ]
+
+  # RFC 8252 loopback redirects (localhost / 127.0.0.1 / [::1], any port).
+  # config.allow_loopback_redirects = true
+
+  # Redirect hosts shown as "verified" on the consent screen; others are flagged
+  # as unverified applications.
+  # config.verified_redirect_hosts = %w[claude.ai chatgpt.com]
+
+  # Reject unknown scopes (registration + /oauth/authorize invalid_scope).
+  # config.strict_scope_validation = true
+
   # ============================================================================
   # SCOPE CONFIGURATION
   # ============================================================================
@@ -195,7 +238,6 @@ Mcp::Auth.configure do |config|
   #        * :required - Whether scope is required (true/false)
   #        * :pre_selected - Whether scope was in the original request
   #    - @authorization_params: Hash of OAuth parameters to preserve
-end
 
   # ============================================================================
   # JWT SIGNING (OPTIONAL)
@@ -214,6 +256,27 @@ end
   # keep verifying and both keys are published at /.well-known/jwks.json:
   # config.token_signing_additional_public_keys = [ENV['MCP_JWT_PREVIOUS_PUBLIC_KEY']]
 
+  # ============================================================================
+  # SECRETS HASHED AT REST — TRANSITIONAL DUAL-READ (OPTIONAL)
+  # ============================================================================
+  #
+  # Access tokens, refresh tokens, authorization codes, and client secrets are
+  # stored as one-way SHA-256 digests. While `secret_dual_read` is true (the
+  # default), a presented value is matched against BOTH its digest and any legacy
+  # PLAINTEXT row not yet backfilled, so this version keeps working before and
+  # while the backfill migration runs.
+  #
+  # Upgrading an existing install: `rails g mcp:auth:upgrade && rails db:migrate`
+  # (additive columns) before deploying; once EVERY server runs this version,
+  # `rails g mcp:auth:hash_secrets && rails db:migrate` hashes existing rows.
+  # Older versions (<= 0.5.0) cannot read hashed rows, so rolling back after that
+  # backfill signs every client out.
+  #
+  # Once every row is hashed, HARDEN by turning it off so plaintext-form matches
+  # are rejected:
+  # config.secret_dual_read = false
+end
+
 # ============================================================================
 # PROTECTING YOUR MCP ENDPOINT (RESOURCE SERVER)
 # ============================================================================

data/lib/generators/mcp/auth/templates/views/consent.html.erb

@@ -297,8 +297,21 @@
     <div class="client-info">
       <strong><%%= @client_name %></strong>
       <p>wants to access your MCP server</p>
+      <p class="redirect-info">
+        You will be sent back to <strong><%%= @redirect_host.presence || 'an unknown address' %></strong>
+      </p>
     </div>
 
+    <%% unless @redirect_verified || @redirect_loopback %>
+    <div class="warning-box">
+      <div class="warning-icon">⚠️</div>
+      <div class="warning-text">
+        <strong>Unverified application.</strong> The name above was supplied by the application itself.
+        Only continue if you started this connection and recognize the address above.
+      </div>
+    </div>
+    <%% end %>
+
     <%% if @requested_scopes.any? { |s| s[:required] } %>
     <div class="warning-box">
       <div class="warning-icon">⚠️</div>

data/lib/generators/mcp/auth/upgrade_generator.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/active_record'
+
+module Mcp
+  module Auth
+    module Generators
+      # Step 1 of upgrading an EXISTING install: copies the additive schema
+      # migration (new columns only) without touching the initializer or views
+      # (unlike the full install generator, which would prompt to overwrite them).
+      # Safe to re-run: `migration_template` skips a migration whose class already
+      # exists.
+      #
+      # The columns are purely additive, so older gem versions keep working with
+      # them. Run this migration BEFORE (or as part of) deploying the new version:
+      # the new code needs the columns and answers every OAuth endpoint with a 500
+      # until they exist. Hashing existing secrets is a separate, later step
+      # (`rails generate mcp:auth:hash_secrets`), because older versions cannot
+      # read hashed rows.
+      #
+      #   rails generate mcp:auth:upgrade
+      #   rails db:migrate
+      class UpgradeGenerator < Rails::Generators::Base
+        include ActiveRecord::Generators::Migration
+
+        source_root File.expand_path('templates', __dir__)
+
+        desc 'Adds pending MCP Auth schema migrations for an existing install (no initializer/view changes).'
+
+        def copy_pending_migrations
+          migration_template 'add_mcp_auth_confidential_client_and_reuse.rb.erb',
+                             'db/migrate/add_mcp_auth_confidential_client_and_reuse.rb',
+                             migration_version: migration_version
+        end
+
+        def show_post_install_message
+          say "\nMCP Auth upgrade migration added (new columns only).", :green
+          say 'Next steps:'
+          say '  1. Run it BEFORE the new gem version serves traffic (e.g. in your release'
+          say '     phase). The columns are additive, so servers still on the old version'
+          say '     keep working:'
+          say '       rails db:migrate'
+          say '  2. Deploy this gem version to every server. If you sign with HS256, set a'
+          say '     dedicated MCP_HMAC_SECRET first (not secret_key_base).'
+          say '  3. Once NO server runs the old version, hash existing secrets at rest:'
+          say '       rails generate mcp:auth:hash_secrets && rails db:migrate'
+          say '  4. Then disable the transitional dual-read in config/initializers/mcp_auth.rb:'
+          say '       config.secret_dual_read = false'
+        end
+
+        private
+
+        def migration_version
+          "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+        end
+      end
+    end
+  end
+end