hitch-rails 0.2.0

data/app/controllers/hitch/metadata_controller.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Hitch
+  # OAuth + MCP discovery metadata:
+  #   GET /.well-known/oauth-authorization-server (RFC 8414)
+  #   GET /.well-known/oauth-protected-resource (RFC 9728)
+  class MetadataController < Hitch::PublicEndpointController
+    include Hitch::CorsSupport
+
+    def show
+      cache_discovery_metadata
+
+      render json: {
+        issuer: issuer_url,
+        authorization_endpoint: canonical_endpoint("/oauth/authorize"),
+        token_endpoint: canonical_endpoint("/oauth/token"),
+        revocation_endpoint: canonical_endpoint("/oauth/revoke"),
+        response_types_supported: [ "code" ],
+        grant_types_supported: [ "authorization_code" ],
+        code_challenge_methods_supported: [ "S256" ],
+        scopes_supported: Hitch.configuration.supported_scopes,
+        token_endpoint_auth_methods_supported: Hitch::Client::TOKEN_ENDPOINT_AUTH_METHODS,
+        # RFC 9207 §3. Advertising this is a promise the authorization
+        # response WILL carry `iss` — a conformant client treats an
+        # advertised-but-absent `iss` as a hard failure and refuses the
+        # code exchange. It is only ever true because
+        # AuthorizationsController#build_redirect_uri appends it
+        # unconditionally; the two must never be separated.
+        authorization_response_iss_parameter_supported: issuer_is_https?
+      }.merge(dynamic_client_registration_advertisement).merge(client_id_metadata_advertisement)
+    end
+
+    def resource
+      cache_discovery_metadata
+
+      # RFC 9728 + 2026-07-28 MCP spec: PRM SHOULD include
+      # scopes_supported so resource servers can echo per-tool
+      # required scopes back in 403 challenges.
+      render json: {
+        resource: Hitch.configuration.resource_uri.presence || issuer_url,
+        authorization_servers: [ issuer_url ],
+        bearer_methods_supported: [ "header" ],
+        scopes_supported: Hitch.configuration.supported_scopes
+      }
+    end
+
+    private
+
+    def dynamic_client_registration_advertisement
+      return {} unless Hitch.configuration.dynamic_client_registration_enabled
+
+      { registration_endpoint: canonical_endpoint("/oauth/register") }
+    end
+
+    # RFC 9207 §2: the `iss` value "MUST be a URL that uses the 'https'
+    # scheme". Over plain http the value this server emits is therefore
+    # not a valid issuer identifier, and withholding the advertisement
+    # does not make it one.
+    #
+    # Be clear about what this is: over http the server is NOT conformant
+    # here, and that is deliberate development compatibility, not a
+    # design. It is also not the first deviation on that path — MCP
+    # 2026-07-28 requires every authorization server endpoint be served
+    # over HTTPS, so an http deployment is already outside the spec and
+    # the issuer scheme is the smaller of its problems.
+    #
+    # `iss` is still emitted over http rather than suppressed, so that a
+    # local development flow exercises the same path as production. The
+    # alternative — omit it below https — means the parameter silently
+    # appears for the first time on deploy, in a security control that is
+    # unpleasant to debug remotely. A client that already accepted the
+    # non-conformant http issuer from this same discovery document can
+    # compare the two and pass. A stricter one may well reject the http
+    # issuer during discovery and never reach the comparison — which is
+    # the correct behaviour, and not something emitting `iss` either
+    # causes or cures.
+    #
+    # Withholding the advertisement is what keeps this safe rather than
+    # conformant. Per the spec's validation table, an advertised-but-
+    # unusable value is what makes a conformant client hard-fail; a
+    # present-but-unadvertised one it simply compares.
+    def issuer_is_https?
+      issuer_url.to_s.start_with?("https://")
+    end
+
+    def canonical_endpoint(path)
+      "#{issuer_url}#{path}"
+    end
+
+    # Advertised only when the host has actually enabled CIMD. The flag
+    # is what makes a conformant client stop falling back to Dynamic
+    # Client Registration and send a document URL as its client_id (the
+    # Ruby MCP SDK branches on exactly this), so advertising it while the
+    # server would reject every such client_id turns a working DCR flow
+    # into a broken one.
+    def client_id_metadata_advertisement
+      return {} unless Hitch.configuration.client_id_metadata_enabled
+
+      { client_id_metadata_document_supported: true }
+    end
+
+    # Issuer URLs come from the configured canonical resource origin, not the
+    # request. Keep discovery private and Vary on Host as defense in depth so
+    # an ingress alias cannot cause one virtual host's response to be reused by
+    # another application sharing a cache.
+    def cache_discovery_metadata
+      expires_in 1.hour # private — not shared-cacheable
+
+      existing = response.headers["Vary"]
+      response.headers["Vary"] =
+        existing.present? ? "#{existing}, Host" : "Host"
+    end
+  end
+end

data/app/controllers/hitch/preflights_controller.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Hitch
+  # OPTIONS for the engine-owned auth and discovery routes. A request earns a
+  # 204 only after its Host, Origin, target method, and requested headers pass.
+  class PreflightsController < Hitch::PublicEndpointController
+    include Hitch::CorsSupport
+
+    def show
+      methods = request.path_parameters.fetch(:target_methods).split(",")
+      hitch_preflight(allowed_methods: methods)
+    end
+  end
+end

data/app/controllers/hitch/public_endpoint_controller.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Hitch
+  # Base for the gem's PUBLIC OAuth endpoints (token, register, revoke,
+  # metadata, /.well-known/*). These serve MCP clients (Claude.ai,
+  # Claude Code, ChatGPT, Cursor, etc.) that are NOT browsers and have
+  # NO host Rails session — the OAuth dance brings them to a session,
+  # it doesn't start with one.
+  #
+  # Inherits from ActionController::Base directly (not the host's
+  # ApplicationController) so the host's auth concern, browser-version
+  # guard, layout, helpers, and other before-actions don't apply.
+  # Session cookies / Rack-level middleware still flow because those
+  # live outside the controller layer.
+  #
+  # The consent screen (AuthorizationsController) is deliberately NOT
+  # in this category — it must integrate with the host's auth concern
+  # to identify the user granting consent.
+  class PublicEndpointController < ::ActionController::Base
+    include Hitch::HostValidation
+    include Hitch::IssuerUrl
+    include Hitch::OauthParameterValidation
+
+    # These endpoints serve non-browser MCP clients (CLI / desktop /
+    # server-to-server) that carry no Rails session and no CSRF token —
+    # PKCE verifier or bearer-token possession is the credential, not a
+    # session cookie. A host with CSRF protection enabled (the Rails
+    # default via load_defaults) would otherwise reject every
+    # POST /oauth/token, /oauth/register and /oauth/revoke with 422,
+    # breaking the OAuth flow entirely. Skipping is safe: there is no
+    # cookie-authenticated state here for a forged cross-site request to
+    # act on. The consent screen (AuthorizationsController) is the only
+    # session-backed POST and KEEPS forgery protection.
+    skip_forgery_protection if respond_to?(:skip_forgery_protection)
+  end
+end

data/app/controllers/hitch/registrations_controller.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Hitch
+  # POST /oauth/register — Dynamic Client Registration (RFC 7591).
+  # MCP clients register before starting the OAuth flow. The
+  # client_name they send ("Claude Code", "ChatGPT", etc.) is
+  # attacker-controllable — we persist it for audit fidelity but
+  # consent UIs MUST NOT trust it for display (see authorize#new).
+  class RegistrationsController < Hitch::PublicEndpointController
+    include Hitch::CorsSupport
+    include Hitch::RegistrationAdmission
+    include Hitch::UriValidation
+
+    def create
+      # RegistrationAdmission has already parsed one bounded JSON object
+      # and installed it here — the action never runs otherwise.
+      metadata = request.request_parameters
+
+      # RFC 7591 §2: the authorization server is responsible for
+      # enforcing its URI policy at registration. Without this, a
+      # client could register `javascript:alert(1)` or
+      # `http://attacker.test/cb` and try to use it at authorize.
+      normalized = normalized_registration_metadata(metadata)
+      return if performed?
+
+      candidate_uris = normalized.fetch(:redirect_uris)
+      invalid = candidate_uris.reject { |uri| valid_redirect_uri?(uri) }
+      if invalid.any?
+        return oauth_error(
+          "invalid_redirect_uri",
+          "redirect_uris must contain only https URIs or RFC 8252 loopback http URIs"
+        )
+      end
+
+      auth_method = optional_string_metadata(metadata, "token_endpoint_auth_method") || "none"
+      return if performed?
+
+      unless Hitch::Client::TOKEN_ENDPOINT_AUTH_METHODS.include?(auth_method)
+        return oauth_error(
+          "invalid_client_metadata",
+          "token_endpoint_auth_method must be none or client_secret_basic"
+        )
+      end
+
+      application_type = optional_string_metadata(metadata, "application_type")
+      return if performed?
+
+      client, client_secret = register_client(
+        auth_method,
+        client_name: metadata["client_name"],
+        redirect_uris: candidate_uris,
+        application_type: application_type
+      )
+
+      response_body = {
+        client_id: client.client_id,
+        client_id_issued_at: client.created_at.to_i,
+        client_name: client.client_name,
+        redirect_uris: client.redirect_uris,
+        grant_types: [ "authorization_code" ],
+        response_types: [ "code" ],
+        scope: Hitch.configuration.supported_scopes.join(" "),
+        token_endpoint_auth_method: client.token_endpoint_auth_method
+      }.merge(
+        # Echo what was actually STORED, not what was sent — RFC 7591
+        # §3.2.1 makes the response the authoritative record of registered
+        # metadata, so a client that sent an unrecognized value can tell
+        # it was dropped by diffing its request against this response.
+        # (Not that it reads as an explicit rejection: §2 defaults an
+        # absent application_type to "web", so silence means the default,
+        # not "you declared nothing".)
+        #
+        # Omitted rather than sent as null when undeclared. Scoped to this
+        # one key deliberately: a blanket `.compact` would silently drop
+        # any future nullable field, and §3.2.1 makes some of them —
+        # `client_secret_expires_at` when a secret is issued — REQUIRED.
+        client.application_type ? { application_type: client.application_type } : {}
+      )
+      if client_secret
+        response_body.merge!(
+          client_secret: client_secret,
+          client_secret_issued_at: client.client_secret_issued_at.to_i,
+          client_secret_expires_at: 0
+        )
+      end
+
+      render json: response_body, status: :created
+    end
+
+    private
+
+    def normalized_registration_metadata(metadata)
+      Hitch::Client.normalize_registration_metadata!(
+        client_name: metadata["client_name"],
+        redirect_uris: metadata["redirect_uris"]
+      )
+    rescue Hitch::Client::InvalidRegistrationMetadata
+      oauth_error(
+        "invalid_client_metadata",
+        "client_name and redirect_uris must satisfy the documented size and shape limits"
+      )
+      nil
+    end
+
+    def optional_string_metadata(metadata, key)
+      return unless metadata.key?(key)
+      return metadata[key] if metadata[key].is_a?(String)
+
+      oauth_error("invalid_client_metadata", "#{key} must be a string")
+      nil
+    end
+
+    # Returns [client, client_secret]; the secret is nil for public clients.
+    # Client.register! returns the record and register_confidential! returns
+    # one-time Credentials (its documented contract), so this is where the
+    # two shapes become one.
+    def register_client(auth_method, client_name:, redirect_uris:, application_type:)
+      attributes = {
+        client_id: SecureRandom.uuid,
+        client_name: client_name,
+        redirect_uris: redirect_uris,
+        # Recorded, never enforced: gating loopback redirects on a
+        # declaration would break clients that omit this metadata.
+        application_type: application_type
+      }
+
+      if auth_method == "client_secret_basic"
+        credentials = Hitch::Client.register_confidential!(**attributes)
+        [ credentials.client, credentials.client_secret ]
+      else
+        [ Hitch::Client.register!(**attributes), nil ]
+      end
+    end
+  end
+end

data/app/controllers/hitch/revocations_controller.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Hitch
+  # POST /oauth/revoke — revoke an access token (RFC 7009).
+  # Per the RFC, returns 200 regardless of whether the token exists
+  # so callers can't probe for valid tokens.
+  class RevocationsController < Hitch::PublicEndpointController
+    include Hitch::CorsSupport
+    include Hitch::OauthFormAdmission
+
+    def create
+      return head :ok unless request.media_type == Hitch::OauthRequestParameters::FORM_MEDIA_TYPE
+
+      token_value = oauth_parameters(:token, form_only: true)[:token]
+      if token_value.present?
+        access_token = Hitch::AccessToken.find_by_token(token_value)
+        access_token&.revoke!
+      end
+
+      head :ok
+    rescue Hitch::OauthRequestParameters::Invalid
+      head :ok
+    end
+
+    private
+
+    def reject_oversized_oauth_form_body!
+      head :ok
+    end
+  end
+end

data/app/controllers/hitch/tokens_controller.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Hitch
+  # POST /oauth/token — exchange auth code for access token.
+  #
+  # Public endpoint (no session auth — clients calling from CLI /
+  # browser / desktop reach this without a Rails session). PKCE
+  # verifier is the credential.
+  class TokensController < Hitch::PublicEndpointController
+    include Hitch::CorsSupport
+    include Hitch::OauthFormAdmission
+    include Hitch::UriValidation
+
+    TOKEN_PARAMETER_NAMES = %i[
+      grant_type
+      code
+      client_id
+      client_secret
+      code_verifier
+      resource
+      redirect_uri
+    ].freeze
+
+    def create
+      unless request.media_type == Hitch::OauthRequestParameters::FORM_MEDIA_TYPE
+        return oauth_error("invalid_request", "token requests must use application/x-www-form-urlencoded")
+      end
+
+      oauth = oauth_parameters(*TOKEN_PARAMETER_NAMES, form_only: true)
+      return oauth_error("invalid_request", "grant_type must be authorization_code") unless oauth[:grant_type] == "authorization_code"
+      return oauth_error("invalid_request", "code is required") if oauth[:code].blank?
+      return oauth_error("invalid_request", "code_verifier is required") if oauth[:code_verifier].blank?
+      unless Hitch::Pkce.valid_verifier?(oauth[:code_verifier])
+        return oauth_error("invalid_grant", "Invalid or expired authorization code")
+      end
+      if oauth[:redirect_uri].present? && !valid_redirect_uri?(oauth[:redirect_uri])
+        return oauth_error("invalid_request", "redirect_uri is malformed")
+      end
+
+      resource = require_canonical_resource(oauth[:resource])
+      return unless resource
+
+      client_id = Hitch::ClientAuthentication.resolve(
+        request: request,
+        body_client_id: oauth[:client_id],
+        body_secret_present: oauth[:client_secret].present?
+      )
+      result = Hitch::AccessToken.exchange_authorization_code!(
+        raw_code: oauth[:code],
+        code_verifier: oauth[:code_verifier],
+        client_id: client_id,
+        resource_uri: resource,
+        redirect_uri: oauth[:redirect_uri]
+      )
+
+      return oauth_error("invalid_grant", "Invalid or expired authorization code") if result.nil?
+
+      render json: {
+        access_token: result[:raw_token],
+        token_type: "Bearer",
+        expires_in: Hitch.configuration.access_token_lifetime_seconds,
+        scope: result[:scope]
+      }
+    rescue Hitch::ClientAuthentication::Invalid => error
+      response.headers["WWW-Authenticate"] = 'Basic realm="oauth/token"' if error.http_status == :unauthorized
+      oauth_error(error.oauth_code, error.message, error.http_status)
+    rescue Hitch::AccessToken::OAuthError => e
+      oauth_error(e.oauth_code, e.description)
+    end
+
+    private
+
+    # RFC 6749 section 5.1 requires token responses to be non-cacheable.
+    # This hook runs in OauthFormAdmission before Rails instrumentation, so
+    # successful exchanges and early admission failures get the same policy.
+    def prepare_oauth_form_response!
+      response.headers["Cache-Control"] = "no-store"
+      response.headers["Pragma"] = "no-cache"
+    end
+
+    def reject_oversized_oauth_form_body!
+      oauth_error(
+        "invalid_request",
+        "token request body exceeds #{MAX_REQUEST_BODY_BYTES} bytes",
+        :content_too_large
+      )
+    end
+  end
+end

data/app/models/hitch/access_token.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+module Hitch
+  # OAuth 2.1 access token + authorization code record. Lifecycle:
+  #
+  #   pending   — code minted, awaiting POST /oauth/token exchange
+  #     ↓ exchange_authorization_code! — all bindings verified, then atomically consumed
+  #   active    — token_digest set; usable until expires_at or revoked_at
+  #     ↓ revoke! / expiry
+  #   inactive
+  #
+  # Polymorphic principal: the host controller supplies the signed-in
+  # record, and each row records which model type owns the token via
+  # principal_type + principal_id (standard Rails polymorphic).
+  #
+  # RFC 8707: resource_uri is the audience this token was issued for.
+  # The MCP server validates at token use time that the request's
+  # resource matches token.resource_uri.
+  class AccessToken < ApplicationRecord
+    self.table_name = "hitch_access_tokens"
+
+    # Ten years. Past it a Postgres timestamp overflows, and a SQLite
+    # five-digit year sorts before today's — which would hand an operator a
+    # token that silently never resolves.
+    MAX_LIFETIME_SECONDS = 3650 * 86_400
+
+    class OAuthError < StandardError
+      attr_reader :oauth_code, :description
+
+      def initialize(oauth_code, description)
+        @oauth_code = oauth_code
+        @description = description
+        super(description)
+      end
+    end
+
+    belongs_to :principal, polymorphic: true
+
+    # Raw authorization code is returned to the client via the OAuth
+    # redirect once at issuance; the DB only ever holds the SHA256
+    # digest. This attr_accessor lets create_authorization! surface the
+    # raw code to the controller without persisting it.
+    attr_accessor :raw_authorization_code
+
+    scope :pending, -> { where(token_digest: nil).where("code_expires_at > ?", Time.current) }
+    scope :active,  -> { where.not(token_digest: nil).where(revoked_at: nil).where("expires_at > ?", Time.current) }
+
+    validates :code_challenge, presence: true
+    validates :code_challenge, format: { with: Hitch::Pkce::S256_CHALLENGE }
+    validates :code_challenge_method, inclusion: { in: %w[S256] }
+
+    def expired?
+      expires_at.present? && expires_at < Time.current
+    end
+
+    def revoked?
+      revoked_at.present?
+    end
+
+    def accessible?
+      token_digest.present? && !expired? && !revoked?
+    end
+
+    # Space-delimited scope check per OAuth 2.1 §3.3. Hosts call this to
+    # gate operations behind a specific scope the client requested at
+    # consent — e.g. `token.scope?("write")` before mutating ops.
+    def scope?(scope)
+      return false if scopes.blank? || scope.blank?
+
+      scopes.split(/\s+/).include?(scope.to_s)
+    end
+
+    def self.create_authorization!(principal:, client_id:, client_name:, code_challenge:, code_challenge_method:, scopes: "mcp", redirect_uri: nil, resource_uri: nil)
+      raw_code = SecureRandom.urlsafe_base64(32)
+      record = create!(
+        principal: principal,
+        client_id: client_id,
+        client_name: client_name,
+        redirect_uri: redirect_uri,
+        resource_uri: resource_uri,
+        authorization_code_digest: Digest::SHA256.hexdigest(raw_code),
+        code_challenge: code_challenge,
+        code_challenge_method: code_challenge_method,
+        code_expires_at: Hitch.configuration.authorization_code_lifetime_seconds.seconds.from_now,
+        scopes: scopes
+      )
+      record.raw_authorization_code = raw_code
+      record
+    end
+
+    # Mints a usable access token outside the browser flow, for a headless
+    # agent or a cron job that cannot complete a consent redirect. The
+    # operator at a console with database access is both the resource owner
+    # and the client, so there is no third party for a consent screen to
+    # protect anyone from.
+    #
+    # Runs the real authorization-code exchange rather than writing a row
+    # directly: the PKCE pair is generated and spent here, so the row that
+    # lands is indistinguishable from a browser-issued one and the same code
+    # path is proven by every other test in the suite. The token is returned
+    # once and only its digest is stored, exactly as in the OAuth flow.
+    def self.issue!(principal:, client_id:, client_name: nil, scopes: nil, expires_in: nil)
+      unless client_id.is_a?(String) && !client_id.empty?
+        # The endpoint refuses a token with a blank client_id, so issuing one
+        # would hand back a credential that can never work.
+        raise ArgumentError, "client_id must be a nonempty String"
+      end
+      # uniq like the browser flow's `asked & supported`, which cannot repeat
+      # a scope past the persisted scope-set boundary.
+      granted = Array(scopes).map(&:to_s).uniq.presence || [ Hitch.configuration.supported_scopes.first ]
+      unsupported = granted - Hitch.configuration.supported_scopes
+      unless unsupported.empty?
+        raise ArgumentError,
+          "scopes are not present in Hitch.configuration.supported_scopes: #{unsupported.join(', ')}"
+      end
+      # Seconds, as a number or a Duration. A String is a caller mistake, not
+      # something to guess at: the rake task parses ENV before it gets here,
+      # and Integer("0700") would quietly mean 448.
+      numeric = expires_in.is_a?(Numeric) || expires_in.is_a?(ActiveSupport::Duration)
+      seconds = expires_in.to_i if numeric && expires_in.to_f.finite?
+      unless expires_in.nil? || (seconds&.positive? && seconds <= MAX_LIFETIME_SECONDS)
+        raise ArgumentError,
+          "expires_in must be a positive number of seconds, at most #{MAX_LIFETIME_SECONDS}"
+      end
+
+      resource_uri = Hitch.configuration.resource_uri
+      verifier = SecureRandom.urlsafe_base64(64)
+      # requires_new, not a plain transaction: a bare `transaction` JOINS a
+      # caller's open one, so a host calling issue! inside its own
+      # transaction and rescuing kept the very row this exists to roll back.
+      transaction(requires_new: true) do
+        record = create_authorization!(
+          principal: principal,
+          client_id: client_id,
+          client_name: client_name.presence || client_id,
+          code_challenge: Base64.urlsafe_encode64(Digest::SHA256.digest(verifier), padding: false),
+          code_challenge_method: "S256",
+          resource_uri: resource_uri,
+          scopes: granted.join(" ")
+        )
+        result = exchange_authorization_code!(
+          raw_code: record.raw_authorization_code,
+          code_verifier: verifier,
+          client_id: client_id,
+          resource_uri: resource_uri
+        )
+        raise "Hitch could not issue an access token" if result.nil?
+
+        # The exchange dates every token by the configured lifetime, which is
+        # sized for a browser session. A headless agent asks for its own.
+        record.reload.update!(expires_at: seconds.seconds.from_now) if seconds
+
+        result.fetch(:raw_token)
+      end
+    end
+
+    def self.exchange_authorization_code!(raw_code:, code_verifier:, client_id:, resource_uri:, redirect_uri: nil)
+      unless Hitch::Pkce.valid_verifier?(code_verifier)
+        raise OAuthError.new("invalid_grant", "PKCE verifier is malformed")
+      end
+
+      code_digest = Digest::SHA256.hexdigest(raw_code.to_s)
+      record = pending.find_by(authorization_code_digest: code_digest)
+      return nil unless record
+
+      unless record.client_id == client_id
+        raise OAuthError.new("invalid_grant", "Authorization code was not issued to this client")
+      end
+      # RFC 6749 §4.1.3: a redirect_uri sent to the token endpoint MUST be
+      # identical to the one the code was issued to. Omitting it is legal
+      # (OAuth 2.1 drops the parameter; PKCE carries the binding).
+      if redirect_uri.present? && record.redirect_uri != redirect_uri
+        raise OAuthError.new("invalid_grant", "redirect_uri does not match the authorization request")
+      end
+      unless record.resource_uri == resource_uri
+        raise OAuthError.new("invalid_target", "resource does not match the authorized resource")
+      end
+
+      record.send(:verify_pkce!, code_verifier)
+      raw_token = SecureRandom.urlsafe_base64(32)
+      now = Time.current
+      updated = where(
+        id: record.id,
+        authorization_code_digest: code_digest,
+        token_digest: nil
+      ).where("code_expires_at > ?", now).update_all(
+        token_digest: Digest::SHA256.hexdigest(raw_token),
+        authorization_code_digest: nil,
+        code_expires_at: nil,
+        expires_at: now + Hitch.configuration.access_token_lifetime_seconds.seconds,
+        updated_at: now
+      )
+
+      return nil unless updated == 1
+
+      { raw_token: raw_token, scope: record.scopes }
+    end
+
+    def revoke!
+      update!(revoked_at: Time.current)
+    end
+
+    def self.find_by_token(raw_token)
+      return nil if raw_token.blank?
+
+      active.find_by(token_digest: Digest::SHA256.hexdigest(raw_token))
+    end
+
+    # Operational cleanup. Three classes of rows accumulate that nothing
+    # ever reads again:
+    #
+    #   1) Pending auth codes whose code_expires_at < now — orphaned by
+    #      OAuth flows the client abandoned (closed the browser, etc.).
+    #      No token was issued; the row is unreachable.
+    #   2) Revoked tokens older than `revoked_retention_days`. The
+    #      record is kept for a window so audit logs/billing/etc. can
+    #      look up the principal_id; beyond that, drop.
+    #   3) Expired tokens (expires_at < now) older than
+    #      `revoked_retention_days` — same audit-window argument.
+    #
+    # Returns the number of rows deleted. Idempotent.
+    #
+    # Hosts schedule this via whatever background job framework they
+    # use (Solid Queue / GoodJob / Sidekiq / cron+rake — gem-agnostic).
+    # Example:
+    #
+    #   class CleanupMCPTokensJob < ApplicationJob
+    #     def perform
+    #       Hitch::AccessToken.cleanup_expired!
+    #     end
+    #   end
+    def self.cleanup_expired!(revoked_retention_days: 30)
+      cutoff = revoked_retention_days.days.ago
+      count = 0
+      count += where(token_digest: nil).where("code_expires_at < ?", Time.current).delete_all
+      count += where.not(revoked_at: nil).where("revoked_at < ?", cutoff).delete_all
+      count += where.not(expires_at: nil).where("expires_at < ?", cutoff).delete_all
+      count
+    end
+
+    # RFC 8707 audience validation. Returns false if the token was
+    # issued for a different resource than the one currently asking.
+    # Per the 2026-07-28 MCP authorization spec: "MCP servers MUST
+    # validate that access tokens were issued specifically for them
+    # as the intended audience."
+    # Spec URL: https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization
+    def valid_for_resource?(requested_resource_uri)
+      allow_loopback = Rails.env.local?
+      stored = ResourceUri.canonicalize!(resource_uri, allow_loopback_http: allow_loopback)
+      requested = ResourceUri.canonicalize!(requested_resource_uri, allow_loopback_http: allow_loopback)
+      stored == requested
+    rescue ResourceUri::Invalid
+      false
+    end
+
+    private
+
+    def verify_pkce!(code_verifier)
+      raise OAuthError.new("invalid_grant", "Authorization code expired") if code_expires_at.nil? || code_expires_at < Time.current
+
+      expected = Base64.urlsafe_encode64(Digest::SHA256.digest(code_verifier), padding: false)
+      return if ActiveSupport::SecurityUtils.secure_compare(expected, code_challenge)
+
+      raise OAuthError.new("invalid_grant", "PKCE verification failed")
+    end
+  end
+end