hitch-rails 0.2.0 → 0.4.0

data/app/models/hitch/device_grant.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+module Hitch
+  # RFC 8628 device authorization grant. Lifecycle:
+  #
+  #   pending   — codes minted, awaiting a person on /activate
+  #     ↓ approve! (binds the signed-in principal) | deny!
+  #   approved | denied
+  #     ↓ exchange_device_code! — the polling client's next request
+  #   consumed  — an access token minted through the real exchange path
+  #
+  # Every transition is one conditional UPDATE whose WHERE clause is the
+  # guard, the same discipline as the authorization-code exchange: the
+  # database picks exactly one winner and no half-decided state — approved
+  # but unowned, consumed twice — is ever representable.
+  class DeviceGrant < ApplicationRecord
+    self.table_name = "hitch_device_grants"
+
+    # Crockford base32: RFC 8628 §6.1 wants no easily-confused characters,
+    # and this alphabet drops I, L, O, U while its decoding treats the
+    # survivors' look-alikes as equal. Eight characters is 40 bits, which
+    # together with the per-principal verification quota clears the §5.1
+    # brute-force bar with room to spare.
+    USER_CODE_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+    USER_CODE_LENGTH = 8
+    TOKEN_ENDPOINT_AUTH_METHODS = %w[none client_secret_basic].freeze
+
+    # The token endpoint already rescues AccessToken::OAuthError; a second
+    # error type would only mean a second rescue.
+    OAuthError = Hitch::AccessToken::OAuthError
+
+    belongs_to :principal, polymorphic: true, optional: true
+
+    # Raw codes surface once, in the mint response; only digests are at rest.
+    attr_accessor :raw_device_code, :raw_user_code
+
+    validates :device_code_digest, :user_code_digest, presence: true, on: :create
+    validates :token_endpoint_auth_method, inclusion: { in: TOKEN_ENDPOINT_AUTH_METHODS }
+
+    scope :pending, -> {
+      where(approved_at: nil, denied_at: nil, consumed_at: nil)
+        .where("expires_at > ?", Time.current)
+    }
+
+    # Scopes are clamped here, at mint — every caller's, not just the
+    # endpoint's — so what a grant holds is always grantable and the
+    # exchange can honor it verbatim.
+    def self.mint!(client_id:, scopes:, resource_uri:, token_endpoint_auth_method: nil)
+      granted = Hitch.configuration.clamp_scopes(scopes)
+      token_endpoint_auth_method ||= authentication_method_for(client_id)
+      attempts = 0
+      begin
+        # Both codes regenerate on retry, so whichever unique constraint
+        # tripped, the next attempt is genuinely fresh.
+        raw_device_code = SecureRandom.urlsafe_base64(32)
+        raw_user_code = generate_user_code
+        # requires_new: the retry below must survive a collision inside a
+        # host's open transaction — on PostgreSQL a failed INSERT poisons
+        # the enclosing transaction without a savepoint, turning the retry
+        # into the very 500 it exists to prevent.
+        record = transaction(requires_new: true) do
+          create!(
+            client_id: client_id,
+            device_code_digest: Digest::SHA256.hexdigest(raw_device_code),
+            user_code_digest: Digest::SHA256.hexdigest(raw_user_code),
+            scopes: granted,
+            resource_uri: resource_uri,
+            token_endpoint_auth_method: token_endpoint_auth_method,
+            expires_at: Hitch.configuration.device_code_lifetime_seconds.seconds.from_now
+          )
+        end
+      rescue ActiveRecord::RecordNotUnique
+        # Forty-bit user codes will eventually land on a live pending one.
+        # Retrying keeps the collision invisible; giving up would turn an
+        # unauthenticated 500 into a collision oracle.
+        attempts += 1
+        retry if attempts < 3
+        raise
+      end
+      record.raw_device_code = raw_device_code
+      record.raw_user_code = raw_user_code
+      record
+    end
+
+    # Canonical form: the eight alphabet characters. Strips the punctuation
+    # display adds, uppercases, and maps the look-alikes Crockford base32
+    # deliberately treats as equal (§6.1 — the user's input is normalized,
+    # never rejected for a dash or a lowercase letter).
+    def self.normalize_user_code(input)
+      input.to_s.upcase.gsub(/[^0-9A-Z]/, "").tr("OIL", "011")
+    end
+
+    # XXXX-XXXX, the form mint responses and screens show. Accepts sloppy
+    # input; normalization is a no-op on canonical codes.
+    def self.display_user_code(input)
+      normalize_user_code(input).scan(/.{1,4}/).join("-")
+    end
+
+    def self.find_pending_by_user_code(input)
+      normalized = normalize_user_code(input)
+      return nil unless normalized.length == USER_CODE_LENGTH
+
+      pending.find_by(user_code_digest: Digest::SHA256.hexdigest(normalized))
+    end
+
+    # The decision, its owner, and the user code's erasure land in one
+    # statement: a grant is never approved-but-unowned, a second decision
+    # finds nothing to decide, and only still-pending grants keep a
+    # guessable code alive. Returns false when the code already met a
+    # decision, expired, or never existed.
+    def self.approve!(user_code:, principal:, client_name: nil)
+      raise ArgumentError, "principal must be persisted" unless principal&.persisted?
+
+      decide!(
+        user_code, :approved_at,
+        principal_type: principal.class.polymorphic_name,
+        principal_id: principal.id,
+        client_name: client_name
+      )
+    end
+
+    def self.deny!(user_code:)
+      decide!(user_code, :denied_at)
+    end
+
+    # The poll (RFC 8628 §3.4). Raises the §3.5 responses as OAuthError so
+    # the token endpoint's existing rescue renders them; nil is the generic
+    # invalid_grant, deliberately covering "never existed", "already
+    # consumed", and "lost the race" alike.
+    def self.exchange_device_code!(raw_device_code:, client_id:, resource_uri:, token_endpoint_auth_method:)
+      unless Hitch.configuration.device_authorization_enabled
+        raise OAuthError.new("unsupported_grant_type", "Device authorization is not enabled")
+      end
+
+      record = find_by(device_code_digest: Digest::SHA256.hexdigest(raw_device_code.to_s))
+      return nil unless record
+
+      unless record.client_id == client_id
+        raise OAuthError.new("invalid_grant", "Device code was not issued to this client")
+      end
+      unless record.token_endpoint_auth_method == token_endpoint_auth_method
+        raise ClientAuthentication::Invalid.new(
+          "invalid_client", "Client authentication failed", http_status: :unauthorized
+        )
+      end
+      unless record.resource_uri == resource_uri
+        raise OAuthError.new("invalid_target", "resource does not match the authorized resource")
+      end
+
+      # Before expiry, deliberately: a person's "no" answers access_denied
+      # however old the grant is. expired_token invites the client to start
+      # the flow over (§3.5), which is not what the person said.
+      if record.denied_at
+        raise OAuthError.new("access_denied", "The request was denied")
+      end
+
+      now = Time.current
+      if record.expires_at <= now
+        raise OAuthError.new("expired_token", "Device code expired")
+      end
+
+      if record.approved_at
+        # The approver may since have been deleted by the host. Consent does
+        # not outlive its owner; the grant is dead, not the server.
+        return nil if record.principal.nil?
+
+        return consume!(record, now: now)
+      end
+
+      # §3.5: one poll per interval claims the window; the rest hear
+      # slow_down. A rejected poll matches zero rows and writes nothing,
+      # so it never advances the window — a client polling too fast is
+      # throttled to the interval, not locked out. A little grace, scaled
+      # so it can never halve the window: a conformant fixed-rate poller's
+      # network jitter must not cost it the permanent +5s a slow_down
+      # demands (§3.5) — the window bounds load, not guessing.
+      interval = Hitch.configuration.device_authorization_interval_seconds
+      window_opens = now - interval + [ 0.5, interval / 10.0 ].min
+      claimed = where(id: record)
+        .where("last_polled_at IS NULL OR last_polled_at <= ?", window_opens)
+        .update_all(last_polled_at: now, updated_at: now)
+      if claimed == 1
+        raise OAuthError.new("authorization_pending", "The authorization request is still pending")
+      end
+
+      raise OAuthError.new("slow_down", "Polling faster than the interval")
+    end
+
+    # Rows are held a day past expiry so the §3.5 answer a polling client
+    # hears — expired_token, or access_denied for a denied grant — does
+    # not depend on when the host's cleanup job happens to run. Past the
+    # floor the row goes: any token issued through it lives on in
+    # hitch_access_tokens, which carries the durable audit trail. Same
+    # host-scheduled contract as AccessToken.cleanup_expired!.
+    def self.cleanup_expired!
+      where("expires_at < ?", 1.day.ago).delete_all
+    end
+
+    def self.generate_user_code
+      SecureRandom.alphanumeric(USER_CODE_LENGTH, chars: USER_CODE_ALPHABET.chars)
+    end
+    private_class_method :generate_user_code
+
+    def self.authentication_method_for(client_id)
+      client = Hitch::Client.find_by(client_id: client_id)
+      client&.confidential_client? ? "client_secret_basic" : "none"
+    end
+    private_class_method :authentication_method_for
+
+    def self.decide!(user_code, decision_column, attributes = {})
+      digest = Digest::SHA256.hexdigest(normalize_user_code(user_code))
+      now = Time.current
+      pending.where(user_code_digest: digest).update_all(
+        attributes.merge(decision_column => now, user_code_digest: nil, updated_at: now)
+      ) == 1
+    end
+    private_class_method :decide!
+
+    # requires_new for the same reason issue! gives: a bare transaction
+    # joins any open one, and the consumption must roll back if the token
+    # mint fails — a consumed grant with no token is a dead end.
+    def self.consume!(record, now:)
+      result = nil
+      transaction(requires_new: true) do
+        consumed = where(id: record.id, consumed_at: nil)
+          .where.not(approved_at: nil)
+          .update_all(consumed_at: now, device_code_digest: nil, updated_at: now)
+        raise ActiveRecord::Rollback unless consumed == 1
+
+        # The stored, mint-clamped scopes are issued verbatim — consent was
+        # evaluated when it was given, and nothing re-litigates it here.
+        _, result = Hitch::AccessToken.mint_through_exchange!(
+          principal: record.principal,
+          client_id: record.client_id,
+          client_name: record.client_name.presence || record.client_id,
+          resource_uri: record.resource_uri,
+          scopes: record.scopes
+        )
+      end
+      result
+    end
+    private_class_method :consume!
+  end
+end

data/app/views/hitch/activations/confirm.html.erb

@@ -0,0 +1,68 @@
+<%# Device activation: the decision (RFC 8628 §3.3 / §5.4). The code is
+   shown back so the person can confirm it matches what their device
+   displays, and the client is named only by what the server verified —
+   never by what the client called itself. %>
+
+<div class="hitch-rails-activate">
+  <h1>Approve this device?</h1>
+
+  <p class="hitch-rails-activate__code-echo">
+    Code: <code><%= @user_code %></code> — check that your device shows
+    this same code.
+  </p>
+
+  <% if @activation.unverified? %>
+    <p class="hitch-rails-activate__warning">
+      <strong>This application could not be verified right now.</strong>
+      Its identity document did not resolve, so there is nothing
+      trustworthy to show you about who is asking. Approving is disabled;
+      the code will expire on its own. If you started this device
+      yourself, ask it for a fresh code and try again later.
+    </p>
+  <% else %>
+    <p>
+      <strong><%= @activation.display_client_name %></strong>
+      <%= "— a client registered by this server's operator —" if @activation.operator_registered? %>
+      is asking for access to your <%= @brand_name %> account.
+      It will act as you.
+    </p>
+
+    <% if @activation.localhost_only_client? %>
+      <p class="hitch-rails-activate__warning">
+        <strong>This application runs on someone's own computer.</strong>
+        Approve it only if that computer is yours and you started this
+        yourself.
+      </p>
+    <% end %>
+
+    <% if @activation.scopes.present? %>
+      <div class="hitch-rails-activate__scopes">
+        <p>It will be granted the following access:</p>
+        <ul>
+          <% @activation.scopes.each do |scope| %>
+            <li><code><%= scope %></code></li>
+          <% end %>
+        </ul>
+      </div>
+    <% end %>
+
+    <p class="hitch-rails-activate__resource">
+      Resource: <code><%= @activation.grant.resource_uri %></code>
+    </p>
+  <% end %>
+
+  <%= form_with url: activate_path, method: :post, data: { turbo: false } do %>
+    <%= hidden_field_tag :user_code, @user_code %>
+
+    <% unless @activation.unverified? %>
+      <button type="submit" name="decision" value="approve"
+              class="hitch-rails-activate__approve">
+        Approve
+      </button>
+    <% end %>
+    <button type="submit" name="decision" value="deny"
+            class="hitch-rails-activate__deny">
+      Deny
+    </button>
+  <% end %>
+</div>

data/app/views/hitch/activations/done.html.erb

@@ -0,0 +1,18 @@
+<%# Device activation: the outcome. The device learns the same answer on
+   its next poll; this page just tells the person they are finished. %>
+
+<div class="hitch-rails-activate">
+  <% if @decision == :approved %>
+    <h1>Device connected</h1>
+    <p>
+      You can close this page. The device will pick up its access the next
+      time it checks in — usually within a few seconds.
+    </p>
+  <% else %>
+    <h1>Request denied</h1>
+    <p>
+      The device has been told no, and its code no longer works. If this
+      was a code someone sent you, you did exactly the right thing.
+    </p>
+  <% end %>
+</div>

data/app/views/hitch/activations/new.html.erb

@@ -0,0 +1,36 @@
+<%# Device activation: code entry (RFC 8628 §3.3). Host apps override by
+   placing app/views/hitch/activations/new.html.erb in their own tree.
+   The host's layout wraps this template automatically.
+
+   The warning copy below is a security control, not decoration (§5.4):
+   the flow's known abuse is a stranger sending someone a code to enter.
+   Keep that meaning intact when overriding. %>
+
+<div class="hitch-rails-activate">
+  <h1>Connect a device</h1>
+
+  <% if @alert %>
+    <p class="hitch-rails-activate__alert"><%= @alert %></p>
+  <% end %>
+
+  <p>
+    A device or program you started — a coding agent, a script, a server —
+    showed you a short code and pointed you here. Enter the code to see
+    what it is asking for.
+  </p>
+
+  <p class="hitch-rails-activate__warning">
+    <strong>Only enter a code you asked a device for.</strong>
+    If someone sent you this code — in an email, a chat, a phone call —
+    stop. Entering it would give <em>their</em> device access to your
+    <%= @brand_name %> account.
+  </p>
+
+  <%= form_with url: activate_path, method: :post, data: { turbo: false } do |f| %>
+    <%= f.label :user_code, "Code" %>
+    <%= f.text_field :user_code, value: @user_code, autocomplete: "off",
+          autocapitalize: "characters", spellcheck: false,
+          class: "hitch-rails-activate__code" %>
+    <button type="submit" class="hitch-rails-activate__continue">Continue</button>
+  <% end %>
+</div>

data/config/routes.rb

@@ -8,11 +8,20 @@ Hitch::Engine.routes.draw do
   post "oauth/register",  to: "registrations#create", as: :oauth_register
   post "oauth/revoke",    to: "revocations#create",   as: :oauth_revoke
 
+  # Device authorization (RFC 8628): the machine leg mints a code pair, the
+  # person leg approves it. /activate is deliberately short — a human types
+  # it from a screen (§3.3.1). A host route declared before the engine's
+  # mount shadows it; the README says so where /activate is documented.
+  post "oauth/device_authorization", to: "device_authorizations#create", as: :oauth_device_authorization
+  get  "activate", to: "activations#new",    as: :activate
+  post "activate", to: "activations#create"
+
   # Route only real engine endpoints to the dedicated preflight validator.
   match "oauth/authorize", to: "preflights#show", via: :options, defaults: { target_methods: "GET,POST" }
   match "oauth/token",     to: "preflights#show", via: :options, defaults: { target_methods: "POST" }
   match "oauth/register",  to: "preflights#show", via: :options, defaults: { target_methods: "POST" }
   match "oauth/revoke",    to: "preflights#show", via: :options, defaults: { target_methods: "POST" }
+  match "oauth/device_authorization", to: "preflights#show", via: :options, defaults: { target_methods: "POST" }
 
   # Discovery (RFC 8414 + RFC 9728)
   get ".well-known/oauth-authorization-server", to: "metadata#show",     as: :oauth_authorization_server_metadata

data/db/migrate/20260822000000_add_hitch_refresh_tokens.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+class AddHitchRefreshTokens < ActiveRecord::Migration[7.2]
+  def change
+    change_table :hitch_access_tokens, bulk: true do |t|
+      # Same posture as every other secret here: the raw token is returned
+      # once and only its SHA256 digest is at rest.
+      t.string :refresh_token_digest
+      # Idle window. Clamped at mint to the family ceiling, so one comparison
+      # answers "still usable" and no caller has to remember the ceiling.
+      t.datetime :refresh_expires_at
+      # The reuse-detection evidence. A consumed row is what tells a replayed
+      # token apart from a first use, so this is the one column cleanup must
+      # not collect while the family it belongs to is still live.
+      t.datetime :refresh_consumed_at
+
+      # The lineage. Every rotation inserts a new row carrying the family_id
+      # it descended from, so detecting one replay can revoke the whole line
+      # in a single statement. Deliberately a grouping key and not a parent
+      # pointer: revocation is family-wide, detection is per-digest, and
+      # nothing reads the tree. A column is additive later and permanent now.
+      t.string :family_id
+      # Absolute ceiling, copied unchanged down the lineage. Carried on each
+      # row rather than looked up from the root so rotation stays a single
+      # write and outlives the root being collected.
+      t.datetime :family_expires_at
+    end
+
+    add_index :hitch_access_tokens, :refresh_token_digest,
+      unique: true, where: "refresh_token_digest IS NOT NULL"
+    add_index :hitch_access_tokens, :family_id, where: "family_id IS NOT NULL"
+  end
+end

data/db/migrate/20260824000000_create_hitch_device_grants.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+class CreateHitchDeviceGrants < ActiveRecord::Migration[7.2]
+  def change
+    create_table :hitch_device_grants do |t|
+      t.string :client_id, null: false
+      # Audit only, written at approval. Attacker-controllable in both
+      # registration schemes, so nothing displays it as an identity.
+      t.string :client_name
+
+      # Raw codes are returned once at mint; only SHA256 digests are at
+      # rest — the same posture as authorization codes. Both nullable on
+      # purpose: the user code is erased in the same statement that
+      # approves or denies, and the device code in the one that consumes,
+      # so only grants still awaiting that step occupy the guessable
+      # namespace and its unique index.
+      t.string :device_code_digest,
+        index: { unique: true, where: "device_code_digest IS NOT NULL" }
+      t.string :user_code_digest,
+        index: { unique: true, where: "user_code_digest IS NOT NULL" }
+
+      # Nullable, unlike every other principal column in this schema: a
+      # device grant is minted by an unauthenticated machine and owned by
+      # nobody until a signed-in person approves it. String-typed for the
+      # same lossless UUID/ULID reason as hitch_access_tokens. Unindexed:
+      # nothing queries grants by principal — rows live minutes, and the
+      # durable per-principal audit trail is hitch_access_tokens.
+      t.references :principal, polymorphic: true, type: :string, null: true, index: false
+
+      t.string :scopes, null: false, default: "mcp"
+      t.string :resource_uri, null: false
+
+      # Indexed for cleanup_expired!, this table's one non-digest query.
+      t.datetime :expires_at, null: false, index: true
+      # The state machine: pending is all four null. Each is written by a
+      # single conditional UPDATE whose WHERE clause is the guard, so a
+      # grant can never be half-decided or decided twice.
+      t.datetime :approved_at
+      t.datetime :denied_at
+      t.datetime :consumed_at
+      # RFC 8628 §3.5: the poll that claimed the current interval window.
+      t.datetime :last_polled_at
+
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20260824000001_enforce_hitch_device_grant_state.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+class EnforceHitchDeviceGrantState < ActiveRecord::Migration[7.2]
+  def up
+    # These rows are short-lived, unaudited authorization attempts, and the
+    # old schema did not record enough information to reconstruct whether the
+    # polling client authenticated. Restarting an in-flight flow is the only
+    # fail-closed upgrade; issued access tokens live in their own table.
+    execute "DELETE FROM hitch_device_grants"
+
+    add_column :hitch_device_grants, :token_endpoint_auth_method,
+      :string, null: false
+
+    add_check_constraint :hitch_device_grants,
+      "token_endpoint_auth_method IN ('none', 'client_secret_basic')",
+      name: "hitch_device_grants_auth_method_check"
+    add_check_constraint :hitch_device_grants,
+      "NOT (approved_at IS NOT NULL AND denied_at IS NOT NULL)",
+      name: "hitch_device_grants_decision_check"
+    add_check_constraint :hitch_device_grants, <<~SQL.squish,
+      (approved_at IS NULL AND principal_type IS NULL AND principal_id IS NULL)
+      OR
+      (approved_at IS NOT NULL AND principal_type IS NOT NULL AND principal_id IS NOT NULL)
+    SQL
+      name: "hitch_device_grants_principal_check"
+    add_check_constraint :hitch_device_grants,
+      "consumed_at IS NULL OR approved_at IS NOT NULL",
+      name: "hitch_device_grants_consumption_check"
+  end
+
+  def down
+    remove_check_constraint :hitch_device_grants, name: "hitch_device_grants_consumption_check"
+    remove_check_constraint :hitch_device_grants, name: "hitch_device_grants_principal_check"
+    remove_check_constraint :hitch_device_grants, name: "hitch_device_grants_decision_check"
+    remove_check_constraint :hitch_device_grants, name: "hitch_device_grants_auth_method_check"
+    remove_column :hitch_device_grants, :token_endpoint_auth_method
+  end
+end

data/db/migrate/20260824000002_add_operator_registration_provenance_to_hitch_clients.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+class AddOperatorRegistrationProvenanceToHitchClients < ActiveRecord::Migration[7.2]
+  def up
+    # 0.3 stored the token authentication method but not who created the
+    # registration, so an existing confidential row might have come from the
+    # anonymous DCR endpoint. False is the only honest, fail-closed backfill;
+    # the operator can vouch for one by rotating its secret and restating its
+    # display name through hitch:clients:rotate_secret.
+    add_column :hitch_clients, :operator_registered,
+      :boolean, null: false, default: false
+    add_check_constraint :hitch_clients,
+      "operator_registered = FALSE OR token_endpoint_auth_method = 'client_secret_basic'",
+      name: "hitch_clients_operator_registration_check"
+  end
+
+  def down
+    remove_check_constraint :hitch_clients, name: "hitch_clients_operator_registration_check"
+    remove_column :hitch_clients, :operator_registered
+  end
+end