hitch-rails 0.2.0 → 0.4.0

data/app/controllers/hitch/activations_controller.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Hitch
+  # GET /activate  — enter a device code (RFC 8628 §3.3)
+  # POST /activate — verify the code, then approve or deny
+  #
+  # The one browser piece of the device flow. Session-authenticated through
+  # the host's ApplicationController like the consent screen: the host's
+  # sign-in gates it, and current_principal is who the approval binds.
+  #
+  # The page's words are part of the security boundary (§5.4): the flow is
+  # "a stranger asks you to approve a code", so the screen says plainly that
+  # a code should only be entered by the person who asked a device for it,
+  # and a ?user_code= prefill only fills the field — approving always takes
+  # the person's own submit.
+  class ActivationsController < Hitch::ApplicationController
+    include Hitch::OauthFormAdmission
+    include Hitch::DeviceAuthorizationGate
+
+    # Same declaration and reasoning as the consent POST: state-changing,
+    # session-authenticated, so it must not depend on the host having
+    # forgery protection enabled. Guarded for API-only host bases.
+    protect_from_forgery with: :exception if respond_to?(:protect_from_forgery)
+
+    # This is a page a person is looking at: every malformed input — a
+    # blank code, a doctored decision — answers with the form and a plain
+    # sentence, never the JSON dialect the inherited rescue speaks.
+    rescue_from Hitch::OauthRequestParameters::Invalid do
+      render_new alert: "Enter the code your device is showing."
+    end
+
+    before_action do
+      # A page for a person, in exactly one dialect: a .json path or a
+      # JSON Accept header must render the HTML answer, not a
+      # MissingTemplate 500.
+      request.format = :html
+      @brand_name = Hitch.configuration.brand_name
+    end
+
+    def new
+      return unless admit_oauth_endpoint!
+      return require_principal! unless current_principal
+
+      # Prefill from verification_uri_complete. Display only — §5.4 wants
+      # the person to see the code and confirm it matches their device, so
+      # a prefilled form still submits by hand.
+      @user_code = DeviceGrant.display_user_code(params[:user_code])
+    end
+
+    def create
+      return require_principal! unless current_principal
+
+      oauth = oauth_parameters(:user_code, :decision, form_only: true)
+      # Absent field, same answer as a blank one — and before the quota:
+      # neither is a guess.
+      return render_new(alert: "Enter the code your device is showing.") if oauth[:user_code].blank?
+      return unless admit_verification_rate!
+
+      grant = DeviceGrant.find_pending_by_user_code(oauth[:user_code])
+      return unknown_code unless grant
+
+      case oauth[:decision]
+      when nil then confirm(grant, oauth[:user_code])
+      when "approve" then approve(grant, oauth[:user_code])
+      when "deny" then deny(oauth[:user_code])
+      else
+        render_new alert: "Something went wrong with that submission. Enter the code again."
+      end
+    end
+
+    private
+
+    # A signed-out visitor following verification_uri_complete must not
+    # leave the live user code sitting in the host's session store for the
+    # code's whole life. They retype it after signing in — it is on the
+    # device screen in front of them, which §5.4 wants them checking
+    # anyway; a signed-in visitor keeps the prefill.
+    def return_to_after_authenticating_url
+      request.base_url + request.path
+    end
+
+    # Verification is the brute-force surface RFC 8628 §5.1 rate-limits, and
+    # the decision POST carries the code too, so every branch of create sits
+    # behind this. Checked per signed-in principal, after authentication —
+    # anonymous traffic cannot drain a person's budget — and after parsing:
+    # a blank or malformed submission is not a guess and spends none either.
+    # Not hitch_admit_rate!: this refusal is a page for a person, not an
+    # OAuth error body.
+    def admit_verification_rate!
+      Hitch::DeviceAuthorizationRateLimit.check_verification!(principal: current_principal)
+      true
+    rescue Hitch::RateLimitStore::Exceeded => error
+      response.headers["Retry-After"] = error.retry_after.to_s
+      render_new alert: "Too many attempts. Wait a minute and try again.", status: :too_many_requests
+      false
+    rescue Hitch::RateLimitStore::Unavailable
+      render_new alert: "Code entry is temporarily unavailable. Try again shortly.",
+        status: :service_unavailable
+      false
+    end
+
+    def confirm(grant, user_code, activation: nil)
+      @activation = activation || DeviceActivation.new(grant, principal: current_principal)
+      @user_code = DeviceGrant.display_user_code(user_code)
+      render :confirm
+    end
+
+    def approve(grant, user_code)
+      activation = DeviceActivation.new(grant, principal: current_principal)
+      # No Approve for a client that cannot be verified right now. The
+      # grant is live and pending, so answer with the honest confirm
+      # screen — "used or expired" would be false, and the failure may be
+      # transient (a rate-limited or momentarily unreachable document).
+      # The same activation is threaded through, so the screen shows the
+      # state this decision was refused on.
+      return confirm(grant, user_code, activation: activation) if activation.unverified?
+
+      decided = DeviceGrant.approve!(
+        user_code: user_code,
+        principal: current_principal,
+        client_name: activation.audit_client_name
+      )
+      return unknown_code unless decided
+
+      @decision = :approved
+      render :done
+    end
+
+    def deny(user_code)
+      return unknown_code unless DeviceGrant.deny!(user_code: user_code)
+
+      @decision = :denied
+      render :done
+    end
+
+    # One message for never-existed, expired, and already-decided alike: a
+    # more specific answer would tell a guesser which codes are live.
+    def unknown_code
+      render_new alert: "That code isn't waiting for approval. " \
+        "It may have expired or already been used — ask your device for a fresh one."
+    end
+
+    # Assigns everything the template needs itself: some callers run from
+    # admission, before the before_action.
+    def render_new(alert:, status: :unprocessable_entity)
+      request.format = :html
+      @alert = alert
+      @user_code = nil
+      @brand_name = Hitch.configuration.brand_name
+      render :new, status: status
+    end
+
+    def preserve_oauth_authenticity_token?
+      true
+    end
+
+    def reject_oversized_oauth_form_body!
+      render_new alert: "That submission was too large. Enter just the short code your device is showing.",
+        status: :content_too_large
+    end
+  end
+end

data/app/controllers/hitch/application_controller.rb

@@ -55,5 +55,35 @@ module Hitch
 
       nil
     end
+
+    private
+
+    def require_principal!
+      # Remember where the user was headed so the host's auth flow returns
+      # them here after login. Rails 8's built-in authentication reads
+      # session[:return_to_after_authenticating] in after_authentication_url;
+      # normally its own require_authentication callback sets this, but
+      # these controllers skip that callback (see above) and redirect to
+      # login_path themselves, so the return location is set here. Harmless
+      # for hosts that never read the key. Only meaningful on a GET render —
+      # a POST without a session isn't a real flow.
+      session[:return_to_after_authenticating] = return_to_after_authenticating_url if request.get?
+
+      path = Hitch.configuration.login_path
+      target = path.respond_to?(:call) ? path.call(request) : path
+
+      if target.present?
+        redirect_to target, allow_other_host: true
+      else
+        render plain: "Authentication required", status: :unauthorized
+      end
+    end
+
+    # What the host's login flow returns the visitor to. The activation
+    # screen overrides this to drop its query string: the prefill link
+    # carries a live user code, and the session store must not keep one.
+    def return_to_after_authenticating_url
+      request.url
+    end
   end
 end

data/app/controllers/hitch/authorizations_controller.rb

@@ -36,8 +36,9 @@ module Hitch
     # protection enabled — an API-only host, or one that disables it
     # app-wide, would otherwise leave Approve forgeable (an attacker
     # auto-approving an authorization in a logged-in victim's session).
-    # The rendered consent form (form_with) carries the token, so
-    # legitimate submits are unaffected. Guarded: an
+    # The rendered consent form (form_with) carries the token, and
+    # browsers send Sec-Fetch-Site — whichever the host's verification
+    # strategy consults, legitimate submits are unaffected. Guarded: an
     # ActionController::API-derived host base doesn't define the macro,
     # and such a host can't serve the HTML consent screen anyway.
     protect_from_forgery with: :exception if respond_to?(:protect_from_forgery)
@@ -121,32 +122,9 @@ module Hitch
     # already passed exact registered-URI validation, so construct the 302
     # directly and keep the credential out of redirect instrumentation.
     def redirect_to_client(location)
-      response.headers["Cache-Control"] = "no-store"
-      response.headers["Pragma"] = "no-cache"
+      hitch_no_store!
       response.headers["Location"] = location
       head :found
     end
-
-    def require_principal!
-      # Remember where the user was headed so the host's auth flow returns
-      # them to the consent screen after login. Rails 8's built-in
-      # authentication reads session[:return_to_after_authenticating] in
-      # after_authentication_url; normally its own require_authentication
-      # callback sets this, but the consent controller skips that callback
-      # (see ApplicationController) and redirects to login_path itself, so
-      # we set the return location here. Harmless for hosts that never read
-      # the key. Only meaningful on the GET consent render — a POST without
-      # a session isn't a real flow.
-      session[:return_to_after_authenticating] = request.url if request.get?
-
-      path = Hitch.configuration.login_path
-      target = path.respond_to?(:call) ? path.call(request) : path
-
-      if target.present?
-        redirect_to target, allow_other_host: true
-      else
-        render plain: "Authentication required", status: :unauthorized
-      end
-    end
   end
 end

data/app/controllers/hitch/device_authorizations_controller.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Hitch
+  # POST /oauth/device_authorization — RFC 8628 §3.1: mint a device grant
+  # and hand back the code pair a headless client shows its human.
+  #
+  # Public endpoint, like tokens: the caller is a machine with no session.
+  # One thing it deliberately never does is fetch client metadata — every
+  # CIMD fetch in this gem has a signed-in, rate-limited actor, and this
+  # endpoint has neither, so a CIMD-shaped client_id is accepted as a
+  # string here and resolved on /activate, where the approving person is
+  # the actor.
+  class DeviceAuthorizationsController < Hitch::PublicEndpointController
+    include Hitch::CorsSupport
+    include Hitch::OauthFormAdmission
+    include Hitch::UriValidation
+    include Hitch::ClientResolution
+    include Hitch::DeviceAuthorizationGate
+
+    DEVICE_PARAMETER_NAMES = %i[client_id client_secret scope resource].freeze
+
+    def create
+      unless request.media_type == Hitch::OauthRequestParameters::FORM_MEDIA_TYPE
+        return oauth_error("invalid_request", "device authorization requests must use application/x-www-form-urlencoded")
+      end
+      return unless admit_mint_rate!
+
+      oauth = oauth_parameters(*DEVICE_PARAMETER_NAMES, form_only: true)
+      resource = require_canonical_resource(oauth[:resource])
+      return unless resource
+
+      authentication = resolved_client_authentication(oauth)
+      client_id = authentication.client_id
+      # A device grant needs a client somebody real vouches for: a
+      # metadata document (its host is earned by serving it), or a
+      # confidential client the operator registered — whose row records that
+      # provenance and which just authenticated by its secret. A client that
+      # only vouched for itself via open registration is the §5.4 phishing
+      # shape, whether or not DCR gave it a secret, and cannot mint. A
+      # registered row decides first, exactly as /activate classifies, so
+      # nothing can mint a grant the screen would never approve.
+      live_client = Hitch::Client.find_by(client_id: client_id)
+      voucher_auth_method = case authentication.token_endpoint_auth_method
+      when "client_secret_basic"
+        if authentication.operator_registered &&
+            live_client&.operator_registered_confidential_client?
+          "client_secret_basic"
+        end
+      when "none"
+        if !authentication.registered_client && live_client.nil? &&
+            Hitch::ClientIdMetadata.reference?(client_id)
+          "none"
+        end
+      end
+      unless voucher_auth_method == authentication.token_endpoint_auth_method
+        return oauth_error(
+          "invalid_client",
+          "device authorization requires a client metadata document or an operator-registered client",
+          :unauthorized
+        )
+      end
+
+      grant = Hitch::DeviceGrant.mint!(
+        client_id: client_id,
+        scopes: oauth[:scope],
+        resource_uri: resource,
+        token_endpoint_auth_method: authentication.token_endpoint_auth_method
+      )
+      render_device_authorization(grant)
+    end
+
+    private
+
+    def client_authentication_realm
+      "oauth/device_authorization"
+    end
+
+    def admit_mint_rate!
+      hitch_admit_rate!("Device authorization") do
+        Hitch::DeviceAuthorizationRateLimit.check_mint!(remote_ip: request.remote_ip)
+      end
+    end
+
+    # §3.2. verification_uri comes from the configured issuer, never the
+    # request: a Host-header alias must not leak into a URI a person types.
+    def render_device_authorization(grant)
+      user_code = Hitch::DeviceGrant.display_user_code(grant.raw_user_code)
+      activate = "#{issuer_url}/activate"
+      render json: {
+        device_code: grant.raw_device_code,
+        user_code: user_code,
+        verification_uri: activate,
+        verification_uri_complete: "#{activate}?user_code=#{user_code}",
+        expires_in: Hitch.configuration.device_code_lifetime_seconds,
+        interval: Hitch.configuration.device_authorization_interval_seconds
+      }
+    end
+
+    # RFC 6749 §5.1's non-cacheable rule, applied to the code pair for the
+    # same reason it applies to tokens.
+    def prepare_oauth_form_response!
+      hitch_no_store!
+    end
+
+    def reject_oversized_oauth_form_body!
+      oauth_error(
+        "invalid_request",
+        "device authorization request body exceeds #{MAX_REQUEST_BODY_BYTES} bytes",
+        :content_too_large
+      )
+    end
+  end
+end

data/app/controllers/hitch/metadata_controller.rb

@@ -16,7 +16,7 @@ module Hitch
         token_endpoint: canonical_endpoint("/oauth/token"),
         revocation_endpoint: canonical_endpoint("/oauth/revoke"),
         response_types_supported: [ "code" ],
-        grant_types_supported: [ "authorization_code" ],
+        grant_types_supported: Hitch::GrantTypes.supported,
         code_challenge_methods_supported: [ "S256" ],
         scopes_supported: Hitch.configuration.supported_scopes,
         token_endpoint_auth_methods_supported: Hitch::Client::TOKEN_ENDPOINT_AUTH_METHODS,
@@ -27,7 +27,9 @@ module Hitch
         # 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)
+      }.merge(dynamic_client_registration_advertisement)
+        .merge(device_authorization_advertisement)
+        .merge(client_id_metadata_advertisement)
     end
 
     def resource
@@ -52,6 +54,15 @@ module Hitch
       { registration_endpoint: canonical_endpoint("/oauth/register") }
     end
 
+    # RFC 8628 §4. GrantTypes.supported adds the device grant urn under the
+    # same flag, so the endpoint and the grant advertise and disappear
+    # together.
+    def device_authorization_advertisement
+      return {} unless Hitch.configuration.device_authorization_enabled
+
+      { device_authorization_endpoint: canonical_endpoint("/oauth/device_authorization") }
+    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

data/app/controllers/hitch/registrations_controller.rb

@@ -125,7 +125,13 @@ module Hitch
       }
 
       if auth_method == "client_secret_basic"
-        credentials = Hitch::Client.register_confidential!(**attributes)
+        # A secret proves continuity at the token endpoint; it does not turn
+        # anonymous DCR into an operator endorsement. Device authorization
+        # must be able to distinguish this row from one created at a console.
+        credentials = Hitch::Client.register_confidential!(
+          **attributes,
+          operator_registered: false
+        )
         [ credentials.client, credentials.client_secret ]
       else
         [ Hitch::Client.register!(**attributes), nil ]

data/app/controllers/hitch/revocations_controller.rb

@@ -12,10 +12,7 @@ module Hitch
       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
+      revoke(token_value) if token_value.present?
 
       head :ok
     rescue Hitch::OauthRequestParameters::Invalid
@@ -24,6 +21,18 @@ module Hitch
 
     private
 
+    # RFC 7009 §2.1: the endpoint takes either token type. An access token
+    # revokes itself; a refresh token revokes the family it belongs to,
+    # because the trust a human granted at the consent screen is the family,
+    # and revoking one link would leave the rest of the chain usable.
+    def revoke(token_value)
+      access_token = Hitch::AccessToken.find_by_token(token_value)
+      return access_token.revoke! if access_token
+
+      refresh_token = Hitch::AccessToken.find_by_refresh_token(token_value)
+      Hitch::AccessToken.revoke_family!(refresh_token.family_id) if refresh_token
+    end
+
     def reject_oversized_oauth_form_body!
       head :ok
     end

data/app/controllers/hitch/tokens_controller.rb

@@ -10,6 +10,7 @@ module Hitch
     include Hitch::CorsSupport
     include Hitch::OauthFormAdmission
     include Hitch::UriValidation
+    include Hitch::ClientResolution
 
     TOKEN_PARAMETER_NAMES = %i[
       grant_type
@@ -17,8 +18,11 @@ module Hitch
       client_id
       client_secret
       code_verifier
+      device_code
       resource
       redirect_uri
+      refresh_token
+      scope
     ].freeze
 
     def create
@@ -27,7 +31,20 @@ module Hitch
       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"
+      case oauth[:grant_type]
+      when "authorization_code" then authorization_code_grant(oauth)
+      when "refresh_token" then refresh_token_grant(oauth)
+      when Hitch::GrantTypes::DEVICE_CODE then device_code_grant(oauth)
+      else
+        oauth_error("invalid_request", "grant_type must be #{Hitch::GrantTypes.supported.join(' or ')}")
+      end
+    rescue Hitch::AccessToken::OAuthError => e
+      oauth_error(e.oauth_code, e.description)
+    end
+
+    private
+
+    def authorization_code_grant(oauth)
       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])
@@ -40,11 +57,7 @@ module Hitch
       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?
-      )
+      client_id = resolved_client_id(oauth)
       result = Hitch::AccessToken.exchange_authorization_code!(
         raw_code: oauth[:code],
         code_verifier: oauth[:code_verifier],
@@ -55,27 +68,79 @@ module Hitch
 
       return oauth_error("invalid_grant", "Invalid or expired authorization code") if result.nil?
 
-      render json: {
+      render_token(result)
+    end
+
+    def refresh_token_grant(oauth)
+      return oauth_error("invalid_request", "refresh_token is required") if oauth[:refresh_token].blank?
+
+      resource = require_canonical_resource(oauth[:resource])
+      return unless resource
+
+      client_id = resolved_client_id(oauth)
+      result = Hitch::AccessToken.exchange_refresh_token!(
+        raw_refresh_token: oauth[:refresh_token],
+        client_id: client_id,
+        resource_uri: resource,
+        scopes: oauth[:scope]
+      )
+
+      return oauth_error("invalid_grant", "Invalid or expired refresh token") if result.nil?
+
+      render_token(result)
+    end
+
+    # RFC 8628 §3.4. The model raises the §3.5 polling responses
+    # (authorization_pending, slow_down, access_denied, expired_token) as
+    # OAuthError, so they flow through the same rescue as every other grant.
+    def device_code_grant(oauth)
+      # Before any parameter or client validation: while the feature is off
+      # this grant has exactly one answer (unsupported_grant_type, RFC 6749
+      # §5.2), and no validation — client authentication included — runs
+      # for it. The model repeats the gate for its own callers.
+      unless Hitch.configuration.device_authorization_enabled
+        return oauth_error("unsupported_grant_type", "Device authorization is not enabled")
+      end
+      return oauth_error("invalid_request", "device_code is required") if oauth[:device_code].blank?
+
+      resource = require_canonical_resource(oauth[:resource])
+      return unless resource
+
+      authentication = resolved_client_authentication(oauth)
+      result = Hitch::DeviceGrant.exchange_device_code!(
+        raw_device_code: oauth[:device_code],
+        client_id: authentication.client_id,
+        resource_uri: resource,
+        token_endpoint_auth_method: authentication.token_endpoint_auth_method
+      )
+
+      return oauth_error("invalid_grant", "Invalid or expired device code") if result.nil?
+
+      render_token(result)
+    end
+
+    def client_authentication_realm
+      "oauth/token"
+    end
+
+    # One shape for both grants. A refresh_token key is present only when the
+    # feature is on, so a client cannot read the absence as an error.
+    def render_token(result)
+      body = {
         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)
+      body[:refresh_token] = result[:raw_refresh_token] if result[:raw_refresh_token].present?
+      render json: body
     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"
+      hitch_no_store!
     end
 
     def reject_oversized_oauth_form_body!