WarpEngine 0.5.0: a catalog that can say a title is not yours

A desktop client reading /api/software had no way to learn that a title costs
money. There was nothing in the response to say so, no way to sign in, and no
way to be told "you do not own this" — so a store with paid titles could only
hand the client a 403 at download time and let it guess why.

The fix belongs here rather than in the client. A client serves more than one
store, so anything it knows about a particular one has to arrive from that
store's own API; a rule compiled into the client is a rule that breaks every
other catalog it reads. Three seams, each following the storage adapter's
shape — documented contract, default that is byte for byte the old behaviour,
one config key to replace it:

- **access policy** — visible_software_scope / access_for / authorize_download.
  Every catalog entry now carries an `access` block (gated, entitled, price,
  purchaseUrl, webUrl) and both /api/download and /file/* ask before serving.
  The vocabulary is deliberately generic: a word from one host's domain would
  make every client that reads it specific to that host.
- **client sign-in** — the device authorization grant (RFC 8628), over the
  host's own user model. The approval page stays the host's, because approving
  needs a session and HTML. Tokens are ApplicationTokens with a `catalog`
  scope, so publishing and reading stay separable.
- **service descriptor** — GET /api/service says what this deployment is and
  whether it has a sign-in at all, which is how a client stops guessing.

With no policy and no subject class configured — every deployment today — the
API is unchanged: /api/auth/* answers 404, /api/service reports auth: null, and
the 187 pre-existing examples pass untouched.

A policy that raises is treated as a refusal, not permission. An artifact
served because the gatekeeper crashed is the one failure mode this must not
have, so a broken policy empties the catalog and denies the download.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

app/models/warp_engine/application_token.rb

@@ -6,6 +6,9 @@ module WarpEngine
 
     UPDATE_SCOPE = "update".freeze
     UPLOAD_SCOPE = "upload".freeze
+    # A token held by a *client* rather than a publisher: it reads the catalog and
+    # downloads artifacts, and it never publishes anything.
+    CATALOG_SCOPE = "catalog".freeze
 
     # The generated token is only available in memory at creation time — the DB
     # stores nothing but the SHA256 digest and the non-secret prefix.
@@ -78,6 +81,15 @@ module WarpEngine
       self.owner_type = WarpEngine.config.application_token_owner_class if owner_type.blank?
     end
 
+    # Publishing tokens and client tokens share this table but not their owners: one
+    # belongs to whoever ships software, the other to whoever buys it. Both classes are
+    # the host's to name, and either is acceptable here — which of the two a given token
+    # may do is decided by its scopes, not by its owner.
+    def self.permitted_owner_types
+      [ WarpEngine.config.application_token_owner_class,
+        WarpEngine.config.access_token_owner_class ].compact_blank
+    end
+
     def generate_token
       return if token_digest.present?
 
@@ -87,11 +99,11 @@ module WarpEngine
     end
 
     def owner_type_matches_configuration
-      expected = WarpEngine.config.application_token_owner_class
-      if expected.blank?
+      permitted = self.class.permitted_owner_types
+      if permitted.empty?
         errors.add(:base, "application_token_owner_class is not configured")
-      elsif owner_type != expected
-        errors.add(:owner_type, "must be #{expected}")
+      elsif !permitted.include?(owner_type)
+        errors.add(:owner_type, "must be #{permitted.join(' or ')}")
       end
     end
 

app/models/warp_engine/device_grant.rb

@@ -0,0 +1,97 @@
+module WarpEngine
+  # One pending sign-in from a client that has no browser of its own.
+  #
+  # The shape is RFC 8628's device authorization grant, and the reason for it is that a
+  # desktop client cannot host a login form without asking a person to type a password
+  # into a window that is not a browser. So the client asks for a pair of codes, sends
+  # the person to the host's own page with the short one, and polls with the long one
+  # until somebody approves it.
+  #
+  # Short-lived by design: this row exists for the minute or two between "the client
+  # asked" and "the person answered". What survives it is the ApplicationToken.
+  class DeviceGrant < ApplicationRecord
+    self.table_name = "device_grants"
+
+    # No I, O, 0 or 1: this alphabet is read off one screen and typed into another, and
+    # those four are where that goes wrong.
+    USER_CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789".freeze
+    USER_CODE_LENGTH   = 8
+
+    belongs_to :application_token, class_name: "WarpEngine::ApplicationToken", optional: true
+    belongs_to :subject, polymorphic: true, optional: true
+
+    validates :device_code, presence: true, uniqueness: true
+    validates :user_code, presence: true, uniqueness: true
+    validates :expires_at, presence: true
+
+    scope :pending, -> { where(approved_at: nil, denied_at: nil).where(expires_at: Time.current..) }
+
+    before_validation :generate_codes, on: :create
+    before_validation :set_expiry, on: :create
+
+    def self.find_pending_by_user_code(code)
+      pending.find_by(user_code: normalize_user_code(code))
+    end
+
+    # Typed by a person, so it arrives with whatever case and separators they used.
+    def self.normalize_user_code(code)
+      code.to_s.upcase.gsub(/[^A-Z0-9]/, "")
+    end
+
+    def expired? = expires_at <= Time.current
+    def approved? = approved_at.present?
+    def denied? = denied_at.present?
+
+    # What the polling client is told. Order matters: a denied grant is denied even
+    # after it expires, because "somebody said no" is the more useful answer.
+    def state
+      return :denied if denied?
+      return :approved if approved?
+      return :expired if expired?
+
+      :pending
+    end
+
+    # Grouped for reading aloud and for typing: WARP-K7M2.
+    def formatted_user_code
+      user_code.to_s.scan(/.{1,4}/).join("-")
+    end
+
+    # Housekeeping for a host that wants it: an expired grant has nothing left to give,
+    # and its issued_token would be a live secret nobody is waiting for.
+    def self.sweep_expired!
+      where(expires_at: ...Time.current).where.not(issued_token: nil).update_all(issued_token: nil)
+    end
+
+    def self.ransackable_attributes(auth_object = nil)
+      %w[approved_at client_name created_at denied_at expires_at id subject_id subject_type updated_at user_code]
+    end
+
+    def self.ransackable_associations(auth_object = nil)
+      []
+    end
+
+    private
+
+    def generate_codes
+      self.device_code = SecureRandom.hex(32) if device_code.blank?
+      self.user_code = self.class.generate_user_code if user_code.blank?
+    end
+
+    def self.generate_user_code
+      # Retried rather than trusted: the alphabet is small enough that a collision is
+      # a real, if rare, event, and a unique index would turn it into a 500.
+      10.times do
+        candidate = Array.new(USER_CODE_LENGTH) { USER_CODE_ALPHABET.chars.sample }.join
+        return candidate unless exists?(user_code: candidate)
+      end
+      raise "could not generate a free device user code"
+    end
+
+    def set_expiry
+      self.expires_at ||= WarpEngine.config.device_code_ttl.to_i.seconds.from_now
+    end
+
+    ActiveSupport.run_load_hooks(:warp_engine_device_grant, self)
+  end
+end