kiosk-server 0.5.20

data/lib/kiosk/server/device_authorization.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'digest'
+
+module Kiosk
+  module Server
+    # One account-binding request on the RFC 8628 device-grant wire: a `:claim`
+    # the agent opens and a human approves, or a `:link` a signed-in human
+    # creates already approved. Only SHA-256 digests of its two codes are kept.
+    #
+    # `requested_role` is the role of the human the row belongs to, set by the
+    # operator, never by a client.
+    #
+    # Lifecycle: `:pending → :approved | :denied → :consumed | :expired`.
+    class DeviceAuthorization < Data.define(
+      :id,
+      :device_code_hash,
+      :user_code_hash,
+      :public_key_pem,
+      :kind,
+      :client_id,
+      :requested_role,
+      :status,
+      :user_id,
+      :expires_at,
+      :consumed_at,
+      :created_at
+    )
+      STATUSES = %i[pending approved denied consumed expired].freeze
+
+      KINDS = %i[claim link].freeze
+
+      # A-Z without I/L/O and digits 2-9: 31^8 ≈ 8.5 × 10^11 codes.
+      USER_CODE_ALPHABET = 'ABCDEFGHJKMNPQRSTUVWXYZ23456789'.chars.freeze
+      USER_CODE_LENGTH   = 8
+
+      DEVICE_CODE_BYTES  = 32
+
+      # Seconds.
+      DEFAULT_EXPIRES_IN = 900
+
+      # A caller bug, not an OAuth error.
+      class StateError < StandardError; end
+
+      # The plain codes exist only in this return value. `binding` takes `kind:`,
+      # `public_key_pem:` and `requested_role:`.
+      def self.generate(client_id:, expires_in: DEFAULT_EXPIRES_IN, now: Time.current, **binding)
+        raise ArgumentError, 'expires_in must be > 0' unless expires_in.positive?
+
+        plain_device_code = SecureRandom.urlsafe_base64(DEVICE_CODE_BYTES)
+        plain_user_code = USER_CODE_LENGTH.times.map { USER_CODE_ALPHABET.sample(random: SecureRandom) }.join
+        da = new(
+          id: SecureRandom.uuid, device_code_hash: hash_device_code(plain_device_code),
+          user_code_hash: hash_user_code(plain_user_code), **pending_attributes(client_id, **binding),
+          expires_at: now + expires_in, consumed_at: nil, created_at: now
+        )
+        [plain_device_code, plain_user_code, da]
+      end
+
+      def self.pending_attributes(client_id, kind: :claim, public_key_pem: nil, requested_role: nil)
+        raise ArgumentError, 'client_id required' if client_id.nil? || client_id.to_s.empty?
+
+        { public_key_pem: public_key_pem, kind: kind, client_id: client_id.to_s,
+          requested_role: requested_role&.to_s, status: :pending, user_id: nil }
+      end
+      private_class_method :pending_attributes
+
+      def self.hash_device_code(plain_device_code)
+        Digest::SHA256.hexdigest(plain_device_code)
+      end
+
+      # Expects a code already normalised ({DeviceVerification.normalize_user_code}).
+      def self.hash_user_code(plain_user_code)
+        Digest::SHA256.hexdigest(plain_user_code)
+      end
+
+      def self.display_user_code(plain_user_code)
+        "#{plain_user_code[0, 4]}-#{plain_user_code[4, 4]}"
+      end
+
+      def initialize(status:, kind:, **rest)
+        super(status: member!(STATUSES, status, 'status'), kind: member!(KINDS, kind, 'kind'), **rest)
+      end
+
+      def pending?  = status == :pending
+      def approved? = status == :approved
+      def denied?   = status == :denied
+      def consumed? = status == :consumed
+      def expired?  = status == :expired
+
+      def claim? = kind == :claim
+      def link?  = kind == :link
+
+      # Checked by the consuming endpoints; the stored status lags behind.
+      def expired_at_time?(now = Time.current)
+        now >= expires_at
+      end
+
+      # A nil `role:` keeps the role already on the row (a `:link` row has one).
+      def approve(user_id:, role: nil)
+        raise StateError, "cannot approve a #{status} authorization" unless pending?
+        raise ArgumentError, 'user_id required' if user_id.nil?
+
+        with(status: :approved, user_id: user_id, requested_role: role&.to_s || requested_role)
+      end
+
+      def deny
+        raise StateError, "cannot deny a #{status} authorization" unless pending?
+
+        with(status: :denied)
+      end
+
+      def consume(now: Time.current)
+        raise StateError, "cannot consume a #{status} authorization" unless approved?
+
+        with(status: :consumed, consumed_at: now)
+      end
+
+      def expire
+        raise StateError, "cannot expire a #{status} authorization" unless pending? || approved?
+
+        with(status: :expired)
+      end
+
+      private
+
+      def member!(allowed, value, name)
+        symbol = value.to_sym
+        return symbol if allowed.include?(symbol)
+
+        raise ArgumentError, "#{name} must be one of #{allowed.inspect}, got #{value.inspect}"
+      end
+    end
+  end
+end

data/lib/kiosk/server/device_authorization_stores.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Kiosk
+  module Server
+    # Storage for {DeviceAuthorization} rows: {ActiveRecord} (the default) or
+    # {InMemory} for tests.
+    module DeviceAuthorizationStores
+      class UniqueConstraintError < StandardError; end
+
+      class NotFoundError < StandardError; end
+
+      # An adapter must make {#claim_consume} one atomic operation (never a read
+      # then {#update}), and {#lookup_by_user_code_hash} must answer only pending rows.
+      class Base
+        def create(_device_authorization) = raise(NotImplementedError)
+        def update(_device_authorization) = raise(NotImplementedError)
+        def lookup_by_device_code_hash(_hash) = raise(NotImplementedError)
+        def lookup_by_user_code_hash(_hash) = raise(NotImplementedError)
+        def claim_consume(_device_authorization, now: Time.current) = raise(NotImplementedError)
+      end
+
+      class InMemory < Base
+        def initialize
+          super
+          @by_id = {}
+          @mutex = Mutex.new
+        end
+
+        def create(authorization)
+          @mutex.synchronize do
+            ensure_unique!(authorization)
+            @by_id[authorization.id] = authorization
+          end
+          authorization
+        end
+
+        def update(authorization)
+          @mutex.synchronize do
+            raise NotFoundError, "device_authorization #{authorization.id} not found" unless @by_id.key?(authorization.id)
+
+            @by_id[authorization.id] = authorization
+          end
+          authorization
+        end
+
+        def lookup_by_device_code_hash(hash)
+          @mutex.synchronize do
+            @by_id.values.find { |x| x.device_code_hash == hash }
+          end
+        end
+
+        # nil when the row is no longer approved.
+        def claim_consume(authorization, now: Time.current)
+          @mutex.synchronize do
+            current = @by_id[authorization.id]
+            raise NotFoundError, "device_authorization #{authorization.id} not found" if current.nil?
+            return nil unless current.approved?
+
+            @by_id[authorization.id] = current.consume(now: now)
+          end
+        end
+
+        def lookup_by_user_code_hash(hash)
+          @mutex.synchronize do
+            @by_id.values.find { |x| x.user_code_hash == hash && x.pending? }
+          end
+        end
+
+        def reset!
+          @mutex.synchronize { @by_id.clear }
+        end
+
+        def size
+          @mutex.synchronize { @by_id.size }
+        end
+
+        private
+
+        def ensure_unique!(authorization)
+          rows = @by_id.values
+          raise UniqueConstraintError, 'device_code_hash already exists' if rows.any? { |x| x.device_code_hash == authorization.device_code_hash }
+          return unless authorization.pending? && rows.any? { |x| x.pending? && x.user_code_hash == authorization.user_code_hash }
+
+          raise UniqueConstraintError, 'user_code_hash already exists among pending rows'
+        end
+      end
+
+      class ActiveRecord < Base
+        COLUMNS = %w[id device_code_hash user_code_hash public_key_pem kind client_id requested_role
+                     status user_id expires_at consumed_at created_at].freeze
+        TIME_COLUMNS = %w[expires_at consumed_at created_at].freeze
+
+        def create(authorization)
+          binds = COLUMNS.map { |column| bind_value(authorization.public_send(column)) }
+          connection.exec_query(insert_sql, 'Kiosk device_authorization insert', binds)
+          authorization
+        rescue ::ActiveRecord::RecordNotUnique => e
+          raise UniqueConstraintError, e.message
+        end
+
+        def update(authorization)
+          binds = %i[public_key_pem status user_id consumed_at requested_role id].map do |attribute|
+            bind_value(authorization.public_send(attribute))
+          end
+          updated = connection.exec_query(update_sql, 'Kiosk device_authorization update', binds).to_a
+          raise NotFoundError, "device_authorization #{authorization.id} not found" if updated.empty?
+
+          authorization
+        end
+
+        # nil when the row is no longer approved; the row, not Ruby, decides the race.
+        def claim_consume(authorization, now: Time.current)
+          sql = <<~SQL.squish
+            UPDATE #{table}
+            SET status = 'consumed', consumed_at = $1
+            WHERE id = $2 AND status = 'approved'
+            RETURNING id
+          SQL
+          updated = connection.exec_query(sql, 'Kiosk device_authorization claim', [now, authorization.id]).to_a
+          return nil if updated.empty?
+
+          authorization.consume(now: now)
+        end
+
+        def lookup_by_device_code_hash(hash)
+          sql = <<~SQL.squish
+            SELECT * FROM #{table}
+            WHERE device_code_hash = $1
+            LIMIT 1
+          SQL
+          row = connection.exec_query(sql, 'Kiosk device_authorization by device code', [hash]).to_a.first
+          row && row_to_authorization(row)
+        end
+
+        def lookup_by_user_code_hash(hash)
+          sql = <<~SQL.squish
+            SELECT * FROM #{table}
+            WHERE user_code_hash = $1 AND status = 'pending'
+            LIMIT 1
+          SQL
+          row = connection.exec_query(sql, 'Kiosk device_authorization by user code', [hash]).to_a.first
+          row && row_to_authorization(row)
+        end
+
+        private
+
+        def connection = ::ActiveRecord::Base.lease_connection
+        def table = %("#{Kiosk.configuration.schema}".device_authorizations)
+
+        def insert_sql
+          placeholders = (1..COLUMNS.size).map { |i| "$#{i}" }.join(', ')
+          "INSERT INTO #{table} (#{COLUMNS.join(', ')}) VALUES (#{placeholders})"
+        end
+
+        def update_sql
+          <<~SQL.squish
+            UPDATE #{table}
+            SET public_key_pem = $1, status = $2, user_id = $3, consumed_at = $4, requested_role = $5
+            WHERE id = $6
+            RETURNING id
+          SQL
+        end
+
+        def bind_value(value) = value.is_a?(Symbol) ? value.to_s : value
+
+        def row_to_authorization(row)
+          attributes = COLUMNS.to_h do |column|
+            value = row.fetch(column)
+            [column.to_sym, TIME_COLUMNS.include?(column) ? to_time(value) : value]
+          end
+          DeviceAuthorization.new(**attributes)
+        end
+
+        def to_time(value)
+          return value if value.nil? || value.is_a?(Time)
+
+          Time.parse(value.to_s).utc
+        end
+      end
+    end
+  end
+end

data/lib/kiosk/server/device_code_grant.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # The claim ceremony on the RFC 8628 device-grant wire: binds an agent key
+    # to an existing human account once the human approves.
+    #
+    #   .start    — POST /oauth/device_authorization
+    #   .exchange — POST /oauth/token (grant_type=device_code)
+    module DeviceCodeGrant
+      GRANT_TYPE = 'urn:ietf:params:oauth:grant-type:device_code'
+
+      # Seconds; a faster poll gets `slow_down` (RFC 8628 §3.5).
+      DEFAULT_POLL_INTERVAL = 5
+
+      # Seconds a poll time is remembered; longer than any code lives.
+      POLL_REGISTRY_TTL = 3600
+      @poll_registry = {}
+      @poll_mutex    = Mutex.new
+
+      PROOF_REQUIRED = 'signed proof-of-possession required ' \
+                       '(GET /auth/challenge?public_key=… then sign {aud, nonce, jti})'
+
+      STATUS_FAILURES = {
+        pending: [:authorization_pending, 'the account holder has not yet approved'],
+        denied: [:access_denied, 'the account holder denied the request'],
+        consumed: [:invalid_grant, 'device_code already used'],
+        expired: [:expired_token, 'the device_code has expired']
+      }.freeze
+
+      module_function
+
+      # No role parameter on purpose: the row takes the approving human's role.
+      def start(client_id:,
+                public_key_pem:,
+                store: Kiosk.configuration.device_authorization_store,
+                expires_in: DeviceAuthorization::DEFAULT_EXPIRES_IN,
+                now: Time.current)
+        plain_device_code, plain_user_code, da = DeviceAuthorization.generate(
+          client_id: client_id, kind: :claim, public_key_pem: public_key_pem.to_s.strip,
+          expires_in: expires_in, now: now
+        )
+        store.create(da)
+        { device_code: plain_device_code, user_code: DeviceAuthorization.display_user_code(plain_user_code),
+          expires_in: expires_in, interval: DEFAULT_POLL_INTERVAL, da: da }
+      end
+
+      # Returns `{ok: true, access_token:, …}` or `{ok: false, error:, description:}`
+      # with an RFC 8628 §3.5 error code. The auth toll raises its own errors.
+      def exchange(device_code:, # rubocop:disable Metrics/ParameterLists -- the token controller and the specs pass these by name
+                   signed: nil,
+                   pow: nil,
+                   store: Kiosk.configuration.device_authorization_store,
+                   interval: DEFAULT_POLL_INTERVAL,
+                   now: Time.current)
+        return failure(:invalid_request, 'device_code parameter required') if device_code.to_s.empty?
+
+        hash = DeviceAuthorization.hash_device_code(device_code)
+        pay_toll_once!(device_code, hash, pow, now)
+        da = store.lookup_by_device_code_hash(hash)
+        return failure(:invalid_grant, 'unknown device_code') if da.nil?
+        return failure(:slow_down, 'polling faster than the advertised interval') if polled_too_fast?(hash, interval, now)
+
+        da = expire_if_due(da, store, now)
+        return bind_and_mint(authorization: da, signed: signed, store: store, now: now) if da.approved?
+
+        failure(*STATUS_FAILURES.fetch(da.status))
+      end
+
+      def reset_poll_registry!
+        @poll_mutex.synchronize { @poll_registry.clear }
+      end
+
+      class << self
+        private
+
+        # The first poll of each device code value pays the auth toll; later polls
+        # of that value are free until any code could have expired. The store is
+        # not read first, so an unknown code costs the same work as a live one.
+        def pay_toll_once!(device_code, hash, pow, now)
+          config = Kiosk.configuration
+          paid   = "device_code:#{hash}"
+          return if !AuthToll.on?(config) || config.pow_spent_store.spent?(paid)
+
+          AuthToll.gate(verb: 'oauth/token', body: { device_code: device_code.to_s }, pow: pow, config: config)
+          config.pow_spent_store.mark_spent(paid, now.to_i + DeviceAuthorization::DEFAULT_EXPIRES_IN)
+        end
+
+        def expire_if_due(authorization, store, now)
+          return authorization unless authorization.expired_at_time?(now)
+          return authorization unless authorization.pending? || authorization.approved?
+
+          store.update(authorization.expire)
+        end
+
+        # Possession of the row's key is proven before binding; a failed proof
+        # is `invalid_client` and leaves the row approved for a retry.
+        def bind_and_mint(authorization:, signed:, store:, now:)
+          refusal = possession_refusal(authorization.public_key_pem, signed)
+          return refusal if refusal
+          # Atomic, so two concurrent polls mint one token.
+          return failure(:invalid_grant, 'device_code already used') if store.claim_consume(authorization, now: now).nil?
+
+          token_response(authorization)
+        end
+
+        def possession_refusal(public_key_pem, signed)
+          return failure(:invalid_client, PROOF_REQUIRED) if signed.nil? || signed.to_s.empty?
+          return failure(:invalid_client, 'no public key bound to this authorization') if public_key_pem.blank?
+
+          payload = PopVerifier.verify!(public_key_pem: public_key_pem, signed: signed)
+          AuthChallenge.consume!(public_key_pem: public_key_pem, nonce: payload.fetch(:nonce))
+          nil
+        rescue Errors::Base => e
+          failure(:invalid_client, e.message)
+        end
+
+        def token_response(authorization)
+          role = authorization.requested_role
+          result = AccountBinding.bind!(public_key_pem: authorization.public_key_pem,
+                                        user_id: authorization.user_id, requested_role: role)
+          response = { ok: true, access_token: result[:access_token], token_type: 'Bearer',
+                       expires_in: Kiosk.configuration.access_token_ttl }
+          # RFC 6749 §5.1: the granted scope is the approving human's role.
+          response[:scope] = role if role
+          response
+        end
+
+        def failure(error, description)
+          { ok: false, error: error.to_s, description: description }
+        end
+
+        # Per process; a multi-process origin rate-limits at its edge.
+        def polled_too_fast?(hash, interval, now)
+          @poll_mutex.synchronize do
+            @poll_registry.delete_if { |_, at| now - at > POLL_REGISTRY_TTL }
+            last = @poll_registry[hash]
+            @poll_registry[hash] = now
+            !last.nil? && (now - last) < interval
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kiosk/server/device_verification.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # The human half of the claim ceremony: find, approve or deny a pending
+    # authorization by the code the human typed. An operator's own consent
+    # page may call these instead of {DeviceVerifyController}.
+    module DeviceVerification
+      # The human typed a wrong or expired code.
+      class CodeNotFoundError < StandardError; end
+
+      module_function
+
+      def find_pending(user_code:, store: Kiosk.configuration.device_authorization_store)
+        normalized = normalize_user_code(user_code)
+        return nil if normalized.empty?
+
+        store.lookup_by_user_code_hash(DeviceAuthorization.hash_user_code(normalized))
+      end
+
+      # `role:` is the approving human's own role (`user_idp`'s `Identity#role`,
+      # nil when it reports none); it is required so a custom page cannot omit it by accident.
+      def approve(user_code:, user_id:, role:,
+                  store: Kiosk.configuration.device_authorization_store)
+        raise ArgumentError, 'user_id required' if user_id.nil? || user_id.to_s.empty?
+
+        da = find_pending(user_code: user_code, store: store)
+        raise CodeNotFoundError, 'user_code does not match any pending authorization' if da.nil?
+
+        store.update(da.approve(user_id: user_id, role: role))
+      end
+
+      def deny(user_code:, store: Kiosk.configuration.device_authorization_store)
+        da = find_pending(user_code: user_code, store: store)
+        raise CodeNotFoundError, 'user_code does not match any pending authorization' if da.nil?
+
+        store.update(da.deny)
+      end
+
+      # Drops the `XXXX-XXXX` dash and whitespace; the alphabet is uppercase.
+      def normalize_user_code(raw)
+        raw.to_s.gsub(/[\s-]/, '').upcase
+      end
+    end
+  end
+end