mcp-auth 0.5.0 → 0.6.0

data/lib/mcp/auth/engine.rb

@@ -21,12 +21,46 @@ module Mcp
 
       initializer "mcp_auth.configure" do
         config.mcp_auth = ActiveSupport::OrderedOptions.new
-        config.mcp_auth.oauth_secret = ENV.fetch('MCP_OAUTH_PRIVATE_KEY', nil)
         config.mcp_auth.authorization_server_url = ENV.fetch('MCP_AUTHORIZATION_SERVER_URL', nil)
         config.mcp_auth.access_token_lifetime = 3600 # 1 hour
         config.mcp_auth.refresh_token_lifetime = 2_592_000 # 30 days
         config.mcp_auth.authorization_code_lifetime = 1800 # 30 minutes
       end
+
+      # Keep OAuth credentials out of the host app's logs. Rails' default filters
+      # (:token, :secret, ...) miss the authorization `code` and the PKCE
+      # `code_verifier`, which together are enough to redeem a code; the
+      # redirect back to the client (`Redirected to ...?code=...`) is filtered too.
+      # Anchored regexes, not symbols: Rails matches symbols as SUBSTRINGS across
+      # the whole app (and ActiveRecord filter_attributes), so `:code` would also
+      # mask `postal_code`, `promo_code`, ...
+      OAUTH_FILTER_PARAMETERS = [
+        /\Acode\z/, /\Acode_verifier\z/, /\Aclient_secret\z/, /\Arefresh_token\z/,
+        /\Aaccess_token\z/, /\Aid_token\z/, /\Atoken\z/
+      ].freeze
+
+      initializer 'mcp_auth.filter_parameters' do |app|
+        app.config.filter_parameters |= OAUTH_FILTER_PARAMETERS
+        app.config.filter_redirect << /[?&]code=/
+      end
+
+      # Surface a pending mcp-auth migration at boot so an operator who upgraded
+      # the gem without running migrations gets a clear, actionable warning
+      # instead of a cryptic runtime error on the first OAuth request. Never
+      # raises (missing_columns is fully guarded), so it can't break boot/CI.
+      config.after_initialize do
+        missing = Mcp::Auth::SchemaGuard.missing_columns
+        Rails.logger.warn("[mcp-auth] #{Mcp::Auth::SchemaGuard.guidance(missing)}") if missing.any?
+
+        # Same idea for the signing secret: warn at boot rather than only failing
+        # on the first token request (outside dev/test, where it's a hard error).
+        unless Rails.env.development? || Rails.env.test?
+          problem = Mcp::Auth::Services::TokenService.oauth_secret_problem
+          Rails.logger.warn("[mcp-auth] #{problem}") if problem
+        end
+      rescue StandardError => e
+        Rails.logger.debug { "[mcp-auth] boot checks skipped: #{e.class}" }
+      end
     end
   end
 end

data/lib/mcp/auth/protected_resource.rb

@@ -20,6 +20,21 @@ module Mcp
       extend ActiveSupport::Concern
       include Mcp::Auth::ControllerHelpers
 
+      # Build the RFC 9728 §5.1 / MCP-spec `WWW-Authenticate` header value for a
+      # 401 from a protected MCP resource. Exposed as a plain function (no request
+      # object needed) so it can be used from a Rack middleware guarding /mcp, not
+      # only from this controller concern — a 401 without this header leaves
+      # spec-compliant MCP clients (e.g. MCP Inspector) unable to discover the
+      # protected-resource metadata and refresh/re-authorize.
+      #
+      #   headers['WWW-Authenticate'] =
+      #     Mcp::Auth::ProtectedResource.www_authenticate(request.base_url)
+      def self.www_authenticate(base_url, error: 'invalid_token',
+                                description: 'The access token is missing, invalid, or expired')
+        metadata_url = "#{base_url}/.well-known/oauth-protected-resource"
+        %(Bearer error="#{error}", error_description="#{description}", resource_metadata="#{metadata_url}")
+      end
+
       # Validates the Bearer access token (signature, expiry, revocation status,
       # and — when a resource is configured — the RFC 8707 audience). On success
       # the decoded claims are stashed in request.env for ControllerHelpers and
@@ -66,21 +81,29 @@ module Mcp
         header.split(' ', 2).last.presence
       end
 
-      # Canonical resource identifier for this server (base_url + mcp_server_path),
-      # matching the audience minted into access tokens.
+      # Canonical resource identifier for this server (MCP server origin +
+      # mcp_server_path), matching the audience minted into access tokens.
       def mcp_resource_identifier
         path = Mcp::Auth.configuration&.mcp_server_path.presence || '/mcp'
         path = "/#{path}" unless path.start_with?('/')
-        "#{request.base_url}#{path.chomp('/')}"
+        "#{mcp_server_origin}#{path.chomp('/')}"
+      end
+
+      # The configured mcp_server_url when set, else the request origin (the host
+      # app MUST then restrict hosts via `config.hosts`). Deliberately NOT
+      # authorization_server_url: with a separate authorization server, the MCP
+      # resource (and its metadata) still lives on this app's host.
+      def mcp_server_origin
+        Mcp::Auth.configuration&.mcp_server_url.presence || request.base_url
       end
 
       # RFC 9728 §5.1 / MCP authorization spec: a 401 MUST advertise the
       # protected-resource metadata document via WWW-Authenticate so clients can
-      # bootstrap the OAuth flow.
+      # bootstrap the OAuth flow. Set mcp_server_url to pin the metadata URL so
+      # a forged Host header can't steer clients to attacker-controlled metadata.
       def render_mcp_unauthorized(error, description, status: :unauthorized)
-        metadata_url = "#{request.base_url}/.well-known/oauth-protected-resource"
         response.headers['WWW-Authenticate'] =
-          %(Bearer error="#{error}", error_description="#{description}", resource_metadata="#{metadata_url}")
+          Mcp::Auth::ProtectedResource.www_authenticate(mcp_server_origin, error: error, description: description)
         render json: { error: error, error_description: description }, status: status
       end
     end

data/lib/mcp/auth/schema_guard.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Mcp
+  module Auth
+    # Raised when the loaded gem needs database columns the app hasn't migrated
+    # yet. Carries an actionable message naming the exact command to run.
+    class PendingMigrationError < Mcp::Auth::Error; end
+
+    # Detects the common upgrade hazard: a new gem version ships migrations, the
+    # app is deployed WITHOUT running them, and the code then blows up at runtime
+    # with a cryptic `unknown attribute` / `UndefinedColumn`. This turns that into
+    # an explicit, self-explaining condition — a loud boot warning and a clear
+    # error at the OAuth endpoints — so the operator knows to run `rails db:migrate`.
+    module SchemaGuard
+      # Columns each release added beyond the original schema, keyed by model.
+      # Extend this whenever a future migration adds a column the code relies on.
+      REQUIRED_COLUMNS = {
+        'Mcp::Auth::OauthClient' => %w[token_endpoint_auth_method],
+        'Mcp::Auth::RefreshToken' => %w[family_id revoked_at]
+      }.freeze
+
+      module_function
+
+      # "table.column" entries the code needs but the database is missing. Empty
+      # when the schema is current. NEVER raises and returns [] when the database
+      # isn't available or a table doesn't exist yet (fresh install, `db:create`,
+      # asset precompile, CI without a database) so it can't break boot or tasks.
+      def missing_columns
+        REQUIRED_COLUMNS.flat_map do |model_name, columns|
+          model = model_name.constantize
+          next [] unless model.table_exists?
+
+          (columns - model.column_names).map { |column| "#{model.table_name}.#{column}" }
+        end
+      rescue StandardError => e
+        # ActiveRecord::NoDatabaseError, ConnectionNotEstablished, StatementInvalid,
+        # etc. — we simply can't check here, so treat as "nothing to report".
+        Rails.logger.debug { "[mcp-auth] schema check skipped: #{e.class}" } if defined?(Rails)
+        []
+      end
+
+      # Memoized fast path for the per-request guard. Columns are only ever ADDED
+      # by a migration + restart, so once the schema is current for this process
+      # it stays current — we can cache the affirmative and skip the check on
+      # every subsequent request. A negative result is NOT cached, so the guard
+      # keeps reporting the problem until it's actually resolved.
+      def up_to_date?
+        return true if @up_to_date
+
+        @up_to_date = missing_columns.empty?
+      end
+
+      # Raise unless the schema is current (used where a hard failure is wanted).
+      def check!
+        missing = missing_columns
+        return true if missing.empty?
+
+        raise PendingMigrationError, guidance(missing)
+      end
+
+      def guidance(missing = missing_columns)
+        "mcp-auth #{Mcp::Auth::VERSION} needs a database migration — missing #{missing.join(', ')}. " \
+          'Run `rails g mcp:auth:upgrade && rails db:migrate`, then restart.'
+      end
+    end
+  end
+end

data/lib/mcp/auth/scope_registry.rb

@@ -60,6 +60,18 @@ module Mcp
           @custom_scopes = {}
         end
 
+        # Scopes that may appear in a request without being rejected as unknown:
+        # registered scopes plus the standard OIDC scopes and offline_access.
+        def recognized_scope?(scope)
+          scope_exists?(scope) || (STANDARD_OIDC_SCOPES + %w[offline_access]).include?(scope.to_s)
+        end
+
+        # Tokens of a scope string (or array) that are not recognized.
+        def unknown_scopes(requested_scopes)
+          scopes = requested_scopes.is_a?(String) ? requested_scopes.split : Array(requested_scopes)
+          scopes.reject { |scope| recognized_scope?(scope) }
+        end
+
         # Check if a scope exists
         def scope_exists?(scope)
           available_scopes.key?(scope.to_s)

data/lib/mcp/auth/secret_hashing.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module Mcp
+  module Auth
+    # One-way hashing for the secrets we persist: client secrets, access tokens,
+    # refresh tokens, and authorization codes.
+    #
+    # We only ever *verify* these values against a copy the caller presents later
+    # — we never need to read the original back. That makes a one-way hash
+    # strictly safer than reversible encryption: a database leak yields useless
+    # digests, and there is no decryption key that (if it also leaked) could turn
+    # them back into working credentials.
+    #
+    # The values are high-entropy (>= 256-bit SecureRandom, or signed JWTs), so a
+    # single unsalted SHA-256 is sufficient — there is no dictionary/brute-force
+    # risk the way there is for low-entropy passwords (which would need bcrypt/
+    # argon2). SHA-256 is also deterministic, which lets us look a token up
+    # directly by its digest through the existing unique index.
+    #
+    # Digests are stored with a `sha256$` prefix so they are self-identifying:
+    # this makes the backfill migration idempotent (a value already carrying the
+    # prefix is left alone) and leaves room to introduce a different scheme later
+    # without ambiguity.
+    module SecretHashing
+      PREFIX = 'sha256$'
+
+      module_function
+
+      # Digest a plaintext value for storage/lookup. ALWAYS hashes non-blank
+      # input — including a value that already carries the prefix. This is a
+      # security property, not a nicety: a presented credential is only ever the
+      # raw secret, so if we instead returned an already-`sha256$`-prefixed input
+      # unchanged, an attacker who read the stored digest from the database could
+      # replay that digest verbatim and it would match the row (defeating
+      # hashing-at-rest). Re-hashing a prefixed value means the stored digest is
+      # never itself a valid credential. (The backfill migration achieves
+      # idempotency with its own prefix guard, not via this method.)
+      def digest(value)
+        return value if value.blank?
+
+        "#{PREFIX}#{Digest::SHA256.hexdigest(value.to_s)}"
+      end
+
+      def hashed?(value)
+        value.to_s.start_with?(PREFIX)
+      end
+
+      # Whether transitional dual-read is active (see Configuration#secret_dual_read).
+      # Defaults to true when configuration is absent so an un-configured app
+      # still upgrades safely.
+      def dual_read?
+        config = Mcp::Auth.configuration
+        config.nil? || config.secret_dual_read != false
+      end
+
+      # The stored-column values a presented secret could legitimately match:
+      # always its digest, plus — while dual-read is enabled — the raw plaintext,
+      # so a legacy row not yet backfilled by the migration still resolves. Use
+      # with `where(column: candidates)`.
+      def lookup_candidates(value)
+        return [] if value.blank?
+
+        candidates = [digest(value)]
+        candidates << value.to_s if dual_read? && !hashed?(value)
+        candidates.uniq
+      end
+
+      # Constant-time verification of a presented plaintext against a stored
+      # value. Matches the digest form, and — under dual-read — a legacy plaintext
+      # row as well.
+      def match?(stored, presented)
+        return false if stored.blank? || presented.blank?
+
+        return true if ActiveSupport::SecurityUtils.secure_compare(stored.to_s, digest(presented.to_s))
+
+        dual_read? && !hashed?(stored) &&
+          ActiveSupport::SecurityUtils.secure_compare(stored.to_s, presented.to_s)
+      end
+    end
+  end
+end

data/lib/mcp/auth/services/authorization_service.rb

@@ -5,15 +5,17 @@ module Mcp
     module Services
       class AuthorizationService
         class << self
-          # Generate authorization code with PKCE support
+          # Generate authorization code with PKCE support. The code is returned to
+          # the client in plaintext, but only its digest is persisted (hashed at
+          # rest).
           def generate_authorization_code(params, user:, org:)
             code = SecureRandom.hex(32)
 
             # Use provided scope or default to all registered scopes
             scope = params[:scope].presence || Mcp::Auth::ScopeRegistry.default_scope_string
 
-            authorization_code = Mcp::Auth::AuthorizationCode.create!(
-              code: code,
+            Mcp::Auth::AuthorizationCode.create!(
+              code: Mcp::Auth::SecretHashing.digest(code),
               client_id: params[:client_id],
               redirect_uri: params[:redirect_uri],
               code_challenge: params[:code_challenge],
@@ -22,11 +24,11 @@ module Mcp
               scope: scope,
               user: user,
               org: org,
-              expires_at: authorization_code_lifetime.minutes.from_now
+              expires_at: authorization_code_lifetime.seconds.from_now
             )
 
             Rails.logger.info "[AuthorizationService] Authorization code generated for user #{user.id}"
-            authorization_code.code
+            code
           rescue ActiveRecord::RecordInvalid => e
             Rails.logger.error "[AuthorizationService] Failed to create authorization code: #{e.message}"
             nil
@@ -36,7 +38,9 @@ module Mcp
           def validate_authorization_code(code)
             return nil if code.blank?
 
-            authorization_code = Mcp::Auth::AuthorizationCode.active.find_by(code: code)
+            authorization_code = Mcp::Auth::AuthorizationCode.active
+                                                             .where(code: Mcp::Auth::SecretHashing.lookup_candidates(code))
+                                                             .first
             return nil unless authorization_code
 
             {
@@ -61,7 +65,8 @@ module Mcp
           # and gets nil. Returns the code's data on success, nil if the code was
           # already consumed (or never existed).
           def consume_authorization_code(code)
-            authorization_code = Mcp::Auth::AuthorizationCode.find_by(code: code)
+            authorization_code = Mcp::Auth::AuthorizationCode
+                                 .where(code: Mcp::Auth::SecretHashing.lookup_candidates(code)).first
             return nil unless authorization_code
 
             code_data = {
@@ -101,8 +106,13 @@ module Mcp
 
           private
 
+          # Authorization-code TTL in SECONDS (matching every other lifetime in
+          # the gem). Read from the single canonical config source so an app that
+          # configures via Mcp::Auth.configure and one that relies on defaults
+          # agree; 1800s = 30 minutes. (Historically this was read from a second
+          # config object and applied as `.minutes`, yielding 30-HOUR codes.)
           def authorization_code_lifetime
-            Rails.application.config.mcp_auth.authorization_code_lifetime || 30
+            Mcp::Auth.configuration&.authorization_code_lifetime || 1800
           end
         end
       end

data/lib/mcp/auth/services/token_service.rb

@@ -4,6 +4,14 @@ module Mcp
   module Auth
     module Services
       class TokenService
+        # Clock-skew tolerance (seconds) for `nbf` only, so a token minted by a
+        # server whose clock runs slightly ahead isn't rejected as "not yet
+        # valid". Expiry is deliberately strict — see validate_access_token.
+        CLOCK_SKEW_LEEWAY_SECONDS = 30
+
+        # Claims every access token must carry.
+        REQUIRED_CLAIMS = %w[iss aud sub exp].freeze
+
         class << self
           # Validate access token with optional resource verification (RFC 8707).
           # Supports HS256, RS256, and ES256 — algorithm comes from configuration.
@@ -14,17 +22,36 @@ module Mcp
               payload = decode_with_known_keys(token)
               return nil unless payload
 
-              # Check expiration manually to ensure proper handling
+              # Required claims, checked here too: ruby-jwt versions older than the
+              # `required_claims` decode option silently ignore it, and the gemspec
+              # allows them. Without this, a token lacking `aud` would skip the
+              # audience check below on those versions.
+              return nil unless REQUIRED_CLAIMS.all? { |claim| payload[claim].present? }
+
+              # Expiry is strict (no leeway): this server validates tokens it
+              # issued itself, so there's no cross-machine skew to absorb.
               return nil if payload['exp'] && (payload['exp'] <= Time.current.to_i)
 
+              # Token-use separation: an id_token is signed with the same key/alg
+              # as an access token, so cryptographically it would otherwise verify
+              # here. Reject anything not minted as an access token. (Legacy tokens
+              # without the claim are still accepted; the DB row check below is the
+              # second gate — id_tokens are never stored.)
+              token_use = payload['token_use']
+              return nil unless token_use.nil? || token_use == 'access'
+
               # Revocation check (RFC 7009): a JWT remains cryptographically valid
               # until it expires, so a stored-and-still-present row is what makes
               # `revoke` actually take effect. Without this, destroyed tokens would
-              # keep validating until natural expiry.
-              return nil unless Mcp::Auth::AccessToken.active.exists?(token: token)
-
-              # Validate audience if resource provided (RFC 8707 compliance)
-              if resource && payload['aud'].present? && !audience_matches?(payload['aud'], resource)
+              # keep validating until natural expiry. The row is keyed by the
+              # token's digest (tokens are hashed at rest).
+              candidates = SecretHashing.lookup_candidates(token)
+              return nil unless Mcp::Auth::AccessToken.active.where(token: candidates).exists?
+
+              # Validate audience if a resource was provided (RFC 8707). `aud` is a
+              # required claim (enforced at decode), so a token lacking it never
+              # reaches here — no silent skip on a missing audience.
+              if resource && !audience_matches?(payload['aud'], resource)
                 Rails.logger.warn "[TokenService] Token audience mismatch: expected #{resource}, got #{payload['aud']}"
                 return nil
               end
@@ -46,7 +73,7 @@ module Mcp
           def decode_with_known_keys(token)
             last_error = nil
             verification_keys.each do |key|
-              return JWT.decode(token, key, true, { algorithm: signing_algorithm }).first
+              return JWT.decode(token, key, true, decode_options).first
             rescue JWT::DecodeError => e
               last_error = e
             end
@@ -55,6 +82,23 @@ module Mcp
             nil
           end
 
+          # Decode options shared across verification keys. The algorithm is
+          # pinned to a single value (blocks `alg:none` and RS↔HS confusion);
+          # `exp` is verified strictly and `nbf` with a small clock-skew leeway;
+          # and the
+          # core claims are required so a token missing `iss`/`aud`/`sub`/`exp`
+          # is rejected outright rather than silently passing later checks.
+          def decode_options
+            {
+              algorithm: signing_algorithm,
+              verify_expiration: true,
+              verify_not_before: true,
+              exp_leeway: 0,
+              nbf_leeway: CLOCK_SKEW_LEEWAY_SECONDS,
+              required_claims: REQUIRED_CLAIMS
+            }
+          end
+
           # Generate JWT access token with proper audience binding
           def generate_access_token(data, base_url:)
             user_data = fetch_user_data(data)
@@ -76,6 +120,15 @@ module Mcp
               client_id: data[:client_id],
               email: user_data[:email],
               scope: data[:scope],
+              # Unique token id (RFC 7519 jti). Guarantees every access token is
+              # distinct even when two are issued in the same second for the same
+              # principal/scope (e.g. rapid or concurrent refreshes) — without it
+              # the JWTs would be byte-identical and collide on the unique token
+              # index at storage time.
+              jti: SecureRandom.uuid,
+              # Marks this JWT as an access token so it can't be replayed as an
+              # id_token (or vice versa); verified in validate_access_token.
+              token_use: 'access',
               # Only a non-sensitive API key *identifier* is embedded. A bearer
               # JWT is decodable by anyone holding it (and is stored at rest), so
               # the matching secret MUST NOT be placed in the token — the resource
@@ -97,7 +150,11 @@ module Mcp
             raise
           end
 
-          # Generate refresh token
+          # Generate refresh token. The opaque value is returned to the client in
+          # plaintext, but only its digest is persisted (hashed at rest). Tokens
+          # descend within a `family_id`: the first issuance starts a new family;
+          # a rotation reuses the presented token's family so a later replay can
+          # be detected as reuse.
           def generate_refresh_token(data)
             refresh_token = SecureRandom.hex(32)
 
@@ -106,11 +163,12 @@ module Mcp
 
             begin
               Mcp::Auth::RefreshToken.create!(
-                token: refresh_token,
+                token: SecretHashing.digest(refresh_token),
                 client_id: data[:client_id],
                 scope: data[:scope],
                 user_id: data[:user_id],
                 org_id: data[:org_id],
+                family_id: data[:family_id].presence || SecureRandom.uuid,
                 expires_at: expires_at
               )
 
@@ -122,13 +180,54 @@ module Mcp
             end
           end
 
+          # Look up the refresh-token record for a presented value in ANY state
+          # (active, expired, or revoked) so the caller can implement reuse
+          # detection. Honors dual-read (digest or legacy plaintext).
+          def find_refresh_token(raw)
+            return nil if raw.blank?
+
+            Mcp::Auth::RefreshToken.where(token: SecretHashing.lookup_candidates(raw)).first
+          end
+
+          # Atomically consume a refresh token by flipping revoked_at from NULL.
+          # Returns true only for the request that actually performed the flip, so
+          # concurrent redemptions of the same token can't both rotate.
+          def rotate_refresh_token(record)
+            Mcp::Auth::RefreshToken
+              .where(id: record.id, revoked_at: nil)
+              .update_all(revoked_at: Time.current) == 1
+          end
+
+          # Revoke every still-live token in a family (used on reuse detection).
+          def revoke_refresh_family(family_id)
+            return 0 if family_id.blank?
+
+            Mcp::Auth::RefreshToken
+              .where(family_id: family_id, revoked_at: nil)
+              .update_all(revoked_at: Time.current)
+          end
+
+          # Delete the access tokens for a (user, client) pair. Called on
+          # refresh-token-reuse (theft) detection so the already-issued access
+          # token(s) are cut off immediately, not left valid until natural expiry.
+          # Access tokens aren't grouped by family_id, so we scope by the
+          # principal that the compromised family belonged to.
+          def revoke_access_tokens_for(user_id:, client_id:)
+            Mcp::Auth::AccessToken.where(user_id: user_id, client_id: client_id).delete_all
+          end
+
           # Validate refresh token
           def validate_refresh_token(refresh_token)
             return nil if refresh_token.blank?
 
-            token_record = Mcp::Auth::RefreshToken.find_by(token: refresh_token)
+            token_record = Mcp::Auth::RefreshToken.where(token: SecretHashing.lookup_candidates(refresh_token)).first
             return nil unless token_record
 
+            # A rotated/revoked token is no longer active (RFC 7662): rotation now
+            # marks `revoked_at` instead of deleting the row, so introspection must
+            # exclude it explicitly rather than relying on the row being gone.
+            return nil if token_record.revoked?
+
             # Check if token is expired
             return nil if token_record.expires_at < Time.current
 
@@ -141,18 +240,6 @@ module Mcp
             }
           end
 
-          # Revoke refresh token (RFC 7009)
-          def revoke_refresh_token(refresh_token)
-            return false if refresh_token.blank?
-
-            token_record = Mcp::Auth::RefreshToken.find_by(token: refresh_token)
-            return false unless token_record
-
-            token_record.destroy
-            Rails.logger.info '[TokenService] Refresh token revoked'
-            true
-          end
-
           # Generate complete token response
           def generate_token_response(data, base_url:)
             access_token = generate_access_token(data, base_url: base_url)
@@ -192,6 +279,7 @@ module Mcp
               iss: base_url,
               sub: data[:user_id].to_s,
               aud: data[:client_id],
+              token_use: 'id', # distinguishes this from an access token
               iat: Time.current.to_i,
               exp: Time.current.to_i + token_lifetime
             }
@@ -368,11 +456,44 @@ module Mcp
             pub
           end
 
+          # HMAC secret for HS256 signing. A dedicated secret MUST be configured:
+          # silently reusing Rails' secret_key_base (which also signs cookies and
+          # every MessageVerifier) breaks key separation. Outside development/test
+          # a missing secret — or one that IS secret_key_base, e.g. via an
+          # `ENV.fetch('MCP_HMAC_SECRET', secret_key_base)` initializer — is a hard
+          # error; in dev/test we fall back so the gem still boots.
           def oauth_secret
             secret = Mcp::Auth.configuration&.oauth_secret
+            problem = oauth_secret_problem(secret)
+            return secret if problem.nil?
+
+            raise Mcp::Auth::Error, problem unless local_env?
+
             secret.presence || Rails.application.secret_key_base
           end
 
+          # Why the configured HS256 secret is unacceptable outside dev/test, or
+          # nil when it is fine. Public so boot checks / `mcp_auth:doctor` can
+          # report it before the first token request fails.
+          def oauth_secret_problem(secret = Mcp::Auth.configuration&.oauth_secret)
+            return nil if asymmetric_signing? # RS256/ES256 don't use oauth_secret
+
+            if secret.blank?
+              'Mcp::Auth.configuration.oauth_secret must be set (e.g. ENV["MCP_HMAC_SECRET"]) — refusing to ' \
+                'sign tokens with Rails.application.secret_key_base outside development/test (key separation).'
+            elsif defined?(Rails) && Rails.application &&
+                  ActiveSupport::SecurityUtils.secure_compare(secret.to_s, Rails.application.secret_key_base.to_s)
+              'Mcp::Auth.configuration.oauth_secret must not be Rails.application.secret_key_base — set a ' \
+                'dedicated secret (e.g. ENV["MCP_HMAC_SECRET"], generate with `rails secret`).'
+            end
+          end
+
+          public :oauth_secret_problem
+
+          def local_env?
+            defined?(Rails) && (Rails.env.development? || Rails.env.test?)
+          end
+
           def token_lifetime
             Mcp::Auth.configuration&.access_token_lifetime || 3600
           end
@@ -421,7 +542,7 @@ module Mcp
             expires_at = data[:expires_at] || token_lifetime.seconds.from_now
 
             Mcp::Auth::AccessToken.create!(
-              token: token,
+              token: SecretHashing.digest(token),
               client_id: data[:client_id],
               resource: audience,
               scope: data[:scope],

data/lib/mcp/auth/version.rb

@@ -2,6 +2,6 @@
 
 module Mcp
   module Auth
-    VERSION = "0.5.0"
+    VERSION = "0.6.0"
   end
 end