hitch-rails 0.2.0 → 0.4.0

data/app/models/hitch/access_token.rb

@@ -61,6 +61,36 @@ module Hitch
       token_digest.present? && !expired? && !revoked?
     end
 
+    # The ceiling the whole lineage descends from. Never extended by
+    # rotation, so a chain someone is quietly refreshing forever still stops.
+    def family_expired?
+      family_expires_at.present? && family_expires_at < Time.current
+    end
+
+    # A consumed token presented again inside the grace window: the client
+    # asking for a reply it never received. Outside it, the same request is a
+    # replay of a spent credential and kills the family.
+    def honest_retry?(now = Time.current)
+      return false if refresh_consumed_at.nil?
+
+      refresh_consumed_at + Hitch.configuration.refresh_token_replay_grace_seconds.seconds >= now
+    end
+
+    # RFC 6749 §6: a refresh may narrow the granted scopes and may never
+    # widen them. Asking for nothing keeps what was granted.
+    def narrowed_scopes(requested)
+      granted = scopes.to_s.split(/\s+/)
+      asked = Array(requested).flat_map { |value| value.to_s.split(/\s+/) }.reject(&:empty?).uniq
+      return scopes.to_s if asked.empty?
+
+      widened = asked - granted
+      unless widened.empty?
+        raise OAuthError.new("invalid_scope", "Refresh may narrow scopes but not widen them")
+      end
+
+      asked.join(" ")
+    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.
@@ -92,19 +122,9 @@ module Hitch
     # 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.
+    # protect anyone from. 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 ]
@@ -123,20 +143,52 @@ module Hitch
           "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!(
+        record, result = mint_through_exchange!(
           principal: principal,
           client_id: client_id,
           client_name: client_name.presence || client_id,
+          resource_uri: Hitch.configuration.resource_uri,
+          scopes: granted.join(" ")
+        )
+        # 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
+
+    # The one non-browser token-mint path, shared by issue! and the device
+    # grant's consumption: generate and spend a synthetic PKCE pair through
+    # the real authorization-code exchange, 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. Atomic on its own — a
+    # savepoint under any caller's transaction — so no half-minted row can
+    # outlive a failed exchange whoever calls it.
+    #
+    # Public so DeviceGrant can call its real seam, not part of the public
+    # API (docs/public_api is the contract) — hosts mint through issue!.
+    def self.mint_through_exchange!(principal:, client_id:, client_name:, resource_uri:, scopes:)
+      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
+
+      verifier = SecureRandom.urlsafe_base64(64)
+      transaction(requires_new: true) do
+        record = create_authorization!(
+          principal: principal,
+          client_id: client_id,
+          client_name: client_name,
           code_challenge: Base64.urlsafe_encode64(Digest::SHA256.digest(verifier), padding: false),
           code_challenge_method: "S256",
           resource_uri: resource_uri,
-          scopes: granted.join(" ")
+          scopes: scopes
         )
         result = exchange_authorization_code!(
           raw_code: record.raw_authorization_code,
@@ -146,11 +198,7 @@ module Hitch
         )
         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)
+        [ record, result ]
       end
     end
 
@@ -179,23 +227,126 @@ module Hitch
       record.send(:verify_pkce!, code_verifier)
       raw_token = SecureRandom.urlsafe_base64(32)
       now = Time.current
+      refresh = mint_refresh_attributes(now: now, family_id: nil, family_expires_at: nil)
       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
+        {
+          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
+        }.merge(refresh.fetch(:columns))
       )
 
       return nil unless updated == 1
 
-      { raw_token: raw_token, scope: record.scopes }
+      { raw_token: raw_token, raw_refresh_token: refresh[:raw_refresh_token], scope: record.scopes }
+    end
+
+    # RFC 6749 §6 / OAuth 2.1 §4.3. Consumes the presented refresh token and
+    # issues a successor pair, or refuses.
+    #
+    # Rotation is the same conditional state transition the authorization code
+    # already uses: consumption is the guard, so two concurrent refreshes race
+    # on one UPDATE and exactly one wins. The loser did not steal anything —
+    # it lands in the replay path below, where a just-consumed token is an
+    # honest retry.
+    def self.exchange_refresh_token!(raw_refresh_token:, client_id:, resource_uri:, scopes: nil)
+      unless Hitch.configuration.refresh_tokens_enabled
+        raise OAuthError.new("unsupported_grant_type", "Refresh tokens are not enabled")
+      end
+
+      digest = Digest::SHA256.hexdigest(raw_refresh_token.to_s)
+      record = find_by(refresh_token_digest: digest)
+      return nil unless record
+
+      # Before consumed-state, deliberately. A different client presenting
+      # this token is a mismatched grant, not a theft alarm — revoking a
+      # family on it would let anyone who learns a token log its owner out.
+      unless record.client_id == client_id
+        raise OAuthError.new("invalid_grant", "Refresh token was not issued to this client")
+      end
+      unless record.resource_uri == resource_uri
+        raise OAuthError.new("invalid_target", "resource does not match the authorized resource")
+      end
+      return nil if record.revoked? || record.family_expired?
+
+      now = Time.current
+      # Reuse detection runs before anything the request can get wrong, so a
+      # replay cannot dodge the alarm by also asking for a bad scope.
+      if record.refresh_consumed_at
+        unless record.honest_retry?(now)
+          revoke_family!(record.family_id)
+          raise OAuthError.new("invalid_grant", "Refresh token has already been used")
+        end
+
+        # Inside the window a repeat presentation is the client asking again
+        # for a reply it never got: a fresh pair off the same parent, not a
+        # revoked family.
+        return record.send(:issue_successor!, granted: record.narrowed_scopes(scopes), now: now)
+      end
+      return nil if record.refresh_expires_at.nil? || record.refresh_expires_at < now
+
+      granted = record.narrowed_scopes(scopes)
+      consumed = where(id: record.id, refresh_consumed_at: nil)
+        .update_all(refresh_consumed_at: now, updated_at: now)
+      # Lost the race to a concurrent refresh microseconds ago. That is the
+      # honest-retry case arriving by a different door, not a replay.
+      return nil unless consumed == 1
+
+      record.send(:issue_successor!, granted: granted, now: now)
     end
 
+    # A consumed refresh token presented again by its own client, past the
+    # grace window, is a replay of a credential its owner already spent. The
+    # family is the blast radius: every row descended from that one
+    # authorization, revoked in a single statement.
+    def self.revoke_family!(family_id)
+      return 0 if family_id.blank?
+
+      where(family_id: family_id, revoked_at: nil).update_all(
+        revoked_at: Time.current, updated_at: Time.current
+      )
+    end
+
+    def self.find_by_refresh_token(raw_refresh_token)
+      return nil if raw_refresh_token.blank?
+
+      find_by(refresh_token_digest: Digest::SHA256.hexdigest(raw_refresh_token))
+    end
+
+    # Columns for a freshly minted refresh token. A root passes no family and
+    # starts one; a successor inherits both, so the ceiling is fixed by the
+    # authorization the line descends from and rotation can never extend it.
+    def self.mint_refresh_attributes(now:, family_id:, family_expires_at:)
+      return { columns: {}, raw_refresh_token: nil } unless Hitch.configuration.refresh_tokens_enabled
+
+      raw = SecureRandom.urlsafe_base64(32)
+      # A family's terms are fixed when it starts: a successor inherits the
+      # ceiling its line began with, including the usual absence of one.
+      configured = Hitch.configuration.refresh_token_family_lifetime_seconds
+      ceiling = family_expires_at || (now + configured.seconds if configured)
+      idle = now + Hitch.configuration.refresh_token_lifetime_seconds.seconds
+      {
+        raw_refresh_token: raw,
+        columns: {
+          refresh_token_digest: Digest::SHA256.hexdigest(raw),
+          # Clamped at mint, so "still usable" is one comparison and no caller
+          # has to remember the ceiling separately. Usually there is no
+          # ceiling and this is just the idle window.
+          refresh_expires_at: [ idle, ceiling ].compact.min,
+          refresh_consumed_at: nil,
+          family_id: family_id || SecureRandom.uuid,
+          family_expires_at: ceiling
+        }
+      }
+    end
+    private_class_method :mint_refresh_attributes
+
     def revoke!
       update!(revoked_at: Time.current)
     end
@@ -218,6 +369,26 @@ module Hitch
     #   3) Expired tokens (expires_at < now) older than
     #      `revoked_retention_days` — same audit-window argument.
     #
+    # Class 3 has two floors, because `expires_at` is the ACCESS token's
+    # clock — an hour — and says nothing about the refresh token beside it.
+    #
+    #   - A row still holding a usable refresh token is not dead, however
+    #     long ago its access token lapsed. Collecting it would delete a
+    #     credential the client is about to present.
+    #   - A consumed row is the evidence reuse detection reads. On the
+    #     schedule alone it went while its family was still being refreshed,
+    #     and a replayed stolen token then found nothing and degraded to an
+    #     ordinary invalid_grant — the alarm gone, silently, with no test
+    #     failing. Evidence is held for the same audit window as everything
+    #     else here.
+    #
+    # Both floors defer collection rather than cancelling it: once the
+    # refresh token has expired and the evidence is older than the window,
+    # the row goes. That bounds a long-lived family to one window's worth of
+    # rows however long it keeps rotating. The residual is stated in the
+    # README — a replay of a token consumed longer ago than the window is
+    # refused, but no longer raises the alarm.
+    #
     # Returns the number of rows deleted. Idempotent.
     #
     # Hosts schedule this via whatever background job framework they
@@ -234,7 +405,11 @@ module Hitch
       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 += where.not(expires_at: nil)
+        .where("expires_at < ?", cutoff)
+        .where("refresh_expires_at IS NULL OR refresh_expires_at < ?", Time.current)
+        .where("refresh_consumed_at IS NULL OR refresh_consumed_at < ?", cutoff)
+        .delete_all
       count
     end
 
@@ -255,6 +430,41 @@ module Hitch
 
     private
 
+    # One rotation: a new row carrying the family it descended from, active
+    # the moment it lands. The spent code_challenge is copied because the
+    # column is NOT NULL and validated — it records which authorization this
+    # line came from, which is true of every descendant.
+    def issue_successor!(granted:, now:)
+      raw_token = SecureRandom.urlsafe_base64(32)
+      refresh = self.class.send(
+        :mint_refresh_attributes,
+        now: now,
+        family_id: family_id,
+        family_expires_at: family_expires_at
+      )
+      successor = self.class.create!(
+        {
+          principal_type: principal_type,
+          principal_id: principal_id,
+          client_id: client_id,
+          client_name: client_name,
+          redirect_uri: redirect_uri,
+          resource_uri: resource_uri,
+          code_challenge: code_challenge,
+          code_challenge_method: code_challenge_method,
+          scopes: granted,
+          token_digest: Digest::SHA256.hexdigest(raw_token),
+          expires_at: now + Hitch.configuration.access_token_lifetime_seconds.seconds
+        }.merge(refresh.fetch(:columns))
+      )
+
+      {
+        raw_token: raw_token,
+        raw_refresh_token: refresh[:raw_refresh_token],
+        scope: successor.scopes
+      }
+    end
+
     def verify_pkce!(code_verifier)
       raise OAuthError.new("invalid_grant", "Authorization code expired") if code_expires_at.nil? || code_expires_at < Time.current
 

data/app/models/hitch/authorization_request.rb

@@ -68,7 +68,11 @@ module Hitch
 
       @client =
         if ClientIdMetadata.reference?(client_id)
-          ClientIdMetadata.resolve(client_id, actor: rate_limit_actor)
+          # A principal that cannot be counted must not drive outbound
+          # fetches: the per-actor limit is the bound on amplification, so
+          # no actor means no fetch and the client reads as unknown.
+          actor = rate_limit_actor
+          actor && ClientIdMetadata.resolve(client_id, actor: actor)
         else
           Client.find_by(client_id: client_id)
         end
@@ -79,9 +83,7 @@ module Hitch
     # supports (RFC 6749 §3.3 — the AS MAY narrow). An empty intersection
     # falls back to the default scope so the token is never scopeless.
     def granted_scopes
-      supported = Array.wrap(Hitch.configuration.supported_scopes).map(&:to_s)
-      asked = params[:scope].to_s.split(/\s+/).reject(&:blank?)
-      (asked & supported).presence&.join(" ") || supported.first
+      Hitch.configuration.clamp_scopes(params[:scope])
     end
 
     # The redirect back to the validated redirect_uri, carrying `iss`
@@ -127,7 +129,7 @@ module Hitch
       declared = registered_redirect_uris
       return false if declared.blank?
 
-      declared.all? { |candidate| loopback_redirect_uri?(candidate) }
+      declared.all? { |candidate| loopback_http_uri?(candidate) }
     end
 
     private
@@ -211,34 +213,15 @@ module Hitch
       end
     end
 
-    def loopback_redirect_uri?(candidate)
-      parsed = URI.parse(candidate)
-      parsed.scheme == "http" && loopback_host?(parsed.host)
-    rescue URI::InvalidURIError
-      false
-    end
 
     # Identifies the principal driving a metadata fetch, for per-actor rate
     # limiting — the bound on amplification no DNS or URL trick changes.
-    # Class name included so two principal models cannot collide on an
-    # integer id; nil when the principal has no id, which keeps the limiter
-    # honest rather than silently unlimited.
     def rate_limit_actor
-      return nil unless principal.respond_to?(:id)
-
-      "#{principal.class.name}:#{principal.id}"
+      Hitch::RateLimitStore.actor_for(principal)
     end
 
-    # First matching entry in the configured table, with case/when
-    # semantics: String keys compare exactly, Regexp keys match.
     def friendly_client_name
-      host = redirect_host
-      return nil if host.blank?
-
-      Hitch.configuration.client_names.each do |matcher, label|
-        return label if matcher === host
-      end
-      nil
+      Hitch.configuration.client_label(redirect_host)
     end
 
     def invalid_request(description)

data/app/models/hitch/client.rb

@@ -55,14 +55,21 @@ module Hitch
           client_id: metadata.fetch(:client_id),
           client_name: metadata.fetch(:client_name),
           application_type: normalize_application_type(application_type),
-          token_endpoint_auth_method: "none"
+          token_endpoint_auth_method: "none",
+          operator_registered: false
         )
         client.replace_redirect_uris!(metadata.fetch(:redirect_uris))
         client
       end
     end
 
-    def self.register_confidential!(client_id:, client_name:, redirect_uris:, application_type: nil)
+    def self.register_confidential!(
+      client_id:,
+      client_name:,
+      redirect_uris:,
+      application_type: nil,
+      operator_registered: false
+    )
       metadata = normalize_registration_metadata!(
         client_id: client_id,
         client_name: client_name,
@@ -78,7 +85,8 @@ module Hitch
           application_type: normalize_application_type(application_type),
           token_endpoint_auth_method: "client_secret_basic",
           client_secret_digest: digest_secret(raw_secret),
-          client_secret_issued_at: Time.current
+          client_secret_issued_at: Time.current,
+          operator_registered: operator_registered
         )
         record.replace_redirect_uris!(metadata.fetch(:redirect_uris))
         record
@@ -160,6 +168,10 @@ module Hitch
       token_endpoint_auth_method == "client_secret_basic"
     end
 
+    def operator_registered_confidential_client?
+      confidential_client? && operator_registered?
+    end
+
     def authenticates_secret?(candidate)
       return false unless confidential_client? && client_secret_digest.present? && candidate.present?
 
@@ -223,6 +235,10 @@ module Hitch
       elsif client_secret_digest.blank? || client_secret_issued_at.blank?
         errors.add(:client_secret_digest, "and issued_at are required for a confidential client")
       end
+
+      if operator_registered? && !confidential_client?
+        errors.add(:operator_registered, "requires a confidential client")
+      end
     end
 
     def bounded_client_identifiers

data/app/models/hitch/client_authentication.rb

@@ -5,6 +5,12 @@ module Hitch
     MAX_AUTHORIZATION_BYTES = 4_096
     MAX_SECRET_BYTES = 512
     CONTROL_CHARACTERS = /[\u0000-\u001F\u007F-\u009F]/
+    Resolution = Data.define(
+      :client_id,
+      :token_endpoint_auth_method,
+      :registered_client,
+      :operator_registered
+    )
 
     class Invalid < StandardError
       attr_reader :oauth_code, :http_status
@@ -28,7 +34,12 @@ module Hitch
       client = Hitch::Client.find_by(client_id: client_id)
       invalid_client! unless client&.authenticates_secret?(secret)
 
-      client_id
+      Resolution.new(
+        client_id:,
+        token_endpoint_auth_method: "client_secret_basic",
+        registered_client: true,
+        operator_registered: client.operator_registered?
+      )
     end
 
     def self.public_client_id(client_id, body_secret_present:)
@@ -39,7 +50,12 @@ module Hitch
       client = Hitch::Client.find_by(client_id: client_id)
       invalid_client! if client&.confidential_client?
 
-      client_id
+      Resolution.new(
+        client_id:,
+        token_endpoint_auth_method: "none",
+        registered_client: client.present?,
+        operator_registered: false
+      )
     end
     private_class_method :public_client_id
 

data/app/models/hitch/device_activation.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Hitch
+  # What the /activate confirmation screen may honestly say about the client
+  # behind a pending device grant.
+  #
+  # The device flow delivers nothing to a redirect_uri, so the consent
+  # screen's verified signal — the host the authorization code is actually
+  # sent to — does not survive the trip. What replaces it is a vouching
+  # rule: a device grant is approvable only for a client somebody real
+  # vouches for, and only the voucher's word is displayed. A CIMD client
+  # is branded by its client_id's own URL host, earned by serving the
+  # document there. A confidential client is branded by the name the
+  # operator chose when they registered it at a console. A client that
+  # only ever vouched for itself through open registration — even one DCR
+  # issued a secret — is the §5.4 phishing shape: the mint endpoint refuses it, and this
+  # object independently refuses to verify it, so the guarantee holds
+  # whichever door a grant came through.
+  #
+  # CIMD resolution happens here, with the signed-in approver as the
+  # rate-limit actor — never at the mint endpoint, which has no actor.
+  class DeviceActivation
+    include Hitch::UriValidation
+
+    def initialize(grant, principal:)
+      @grant = grant
+      @principal = principal
+    end
+
+    attr_reader :grant
+
+    # The live voucher must still exist and must agree with the immutable
+    # authentication posture recorded at mint. That refuses both directions
+    # of a registration race: a public/CIMD grant cannot borrow an operator
+    # registration, and a confidential grant cannot fall back to CIMD after
+    # its operator registration disappears.
+    def unverified?
+      case grant.token_endpoint_auth_method
+      when "client_secret_basic" then !operator_registered?
+      when "none" then document.nil?
+      else true
+      end
+    end
+
+    # A confidential client the operator registered at a console; its
+    # display name is the operator's word, and the view says whose word
+    # it is.
+    def operator_registered?
+      grant.token_endpoint_auth_method == "client_secret_basic" &&
+        client&.operator_registered_confidential_client?
+    end
+
+    def display_client_name
+      return client.client_name if operator_registered?
+
+      # hostname, not host: URI#host keeps IPv6 brackets, which would
+      # defeat a client_names entry keyed on the bare address.
+      host = URI.parse(grant.client_id).hostname
+      Hitch.configuration.client_label(host) || host
+    end
+
+    def audit_client_name
+      document&.client_name || client&.client_name || "Unknown"
+    end
+
+    # The consent screen's own-computer warning, carried over: a client
+    # whose every declared redirect is loopback http runs on the user's
+    # machine, not at the host it displays as.
+    def localhost_only_client?
+      declared = document&.redirect_uris
+      declared.present? && declared.all? { |uri| loopback_http_uri?(uri) }
+    end
+
+    def scopes
+      @scopes ||= grant.scopes.to_s.split(/\s+/)
+    end
+
+    private
+
+    # "none" is the posture of a CIMD-vouched grant. A registered row still
+    # wins over URL shape, including one that appeared after mint; it cannot
+    # lend the grant a different voucher than the one the polling client must
+    # present at the token endpoint.
+    def cimd_reference?
+      return @cimd_reference if defined?(@cimd_reference)
+
+      @cimd_reference = grant.token_endpoint_auth_method == "none" &&
+        client.nil? && ClientIdMetadata.document_url?(grant.client_id)
+    end
+
+    # Only a CIMD-classified client resolves — a registered client must
+    # never trigger a fetch however its id is shaped: its voucher is the
+    # operator, and a remote document must not overwrite the operator's
+    # word in the audit trail. Resolution also still honors the flag
+    # (reference? consults it), so a switched-off scheme fetches nothing
+    # and the client reads unverified.
+    def document
+      return @document if defined?(@document)
+
+      @document = if cimd_reference? && ClientIdMetadata.reference?(grant.client_id)
+        ClientIdMetadata.resolve(grant.client_id, actor: Hitch::RateLimitStore.actor_for(@principal))
+      end
+    end
+
+    def client
+      return @client if defined?(@client)
+
+      @client = Client.find_by(client_id: grant.client_id)
+    end
+  end
+end