ask-guests 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 47d3aa99bde7a4fba72632740871294a132d06a492d679c78d5487daa5857506
+  data.tar.gz: 6f937c5d724bd72b036faed46a1490129b37ee59380da63d8ba781b2f243b9db
+SHA512:
+  metadata.gz: 7691132899688d326b7014fd010a7887a107958e717ea1da66b7640fe2fb4b4ace845d0f6c5db23f483904ff13e00d19fe4510b69539a2b1ad91a0cf18c9a429
+  data.tar.gz: 7667b6be0f7ab4634020198f0e30566ea1b3338b79747017c3c7460e8910ca664bbf7222c41902f013d0a161e84481df09bf35b1e69c610ca34756e7c701b72a

data/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## [0.1.0] — 2026-09-15
+
+### Added
+
+- **Guest sessions** — durable anonymous identity: a random session id behind
+  an HMAC-SHA256 signed token (`Ask::Guests::Token`), with pluggable stores
+  (`Stores::Memory`, plus an ActiveRecord adapter).
+- **Metered AI usage** — daily, composable budget policies
+  (`Budget::TurnLimit`, `Budget::TokenQuota`, `Budget::Unlimited`) that check
+  before a turn and record after; counters roll over daily with no scheduled
+  work.
+- **Single-use claiming** — register handlers with `Ask::Guests.claimable`;
+  `Ask::Guests::Claim` transfers every guest-owned record to a real owner in
+  one transaction, re-reading the session under a lock so replayed cookies
+  and double-submits can never claim twice.
+- **Retention** — `Ask::Guests::Sweep` destroys unclaimed sessions inactive
+  past the configured window (seconds); `Rails::SweepJob` schedules it.
+- **Rails adapter** (`ask-guests/rails`) — `Rails::Controller` concern
+  (`allow_guest_access`, `require_visitor`, `guest_session?`),
+  `Rails::ClaimOnAuthentication` for sign-up/sign-in hooks, and the install
+  generator (`bin/rails generate ask:guests:install`).
+- **ActiveRecord adapter** (`ask-guests/active_record`) — `SessionStore` and
+  an abstract `SessionBase` model with an adapter-independent JSON column
+  type (PostgreSQL json/jsonb and SQLite text behave identically) and
+  polymorphic owner columns.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaka Ruto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,195 @@
+# ask-guests
+
+Anonymous, cookie-backed guest access for ask-rb apps. Give visitors a
+durable identity *before* they sign up — with metered AI usage, and a
+single-use claim that moves everything they own into a real account the
+moment they register.
+
+Four concepts, one gem:
+
+| Concept | What it does |
+|---|---|
+| **Identity** | A random session id behind an HMAC-signed token. No fake `User` rows, nothing to enumerate without the secret. |
+| **Ownership** | Hosts register claimable handlers; records owned by a guest carry its session id. |
+| **Metering** | Daily turn/token budgets (composable policies) with automatic rollover — bound anonymous AI spend. |
+| **Claim** | On sign-up/sign-in, transfer all guest records in one transaction, exactly once. |
+
+Plus retention: unclaimed sessions are swept after a configurable window.
+
+The core is framework-agnostic (stdlib only). Adapters plug in persistence
+and web frameworks:
+
+```ruby
+require "ask-guests"                 # core: sessions, budgets, claims, sweep
+require "ask-guests/active_record"   # ActiveRecord store + model base
+require "ask-guests/rails"           # controller concern, auth hook, sweep job
+```
+
+## Installation
+
+```ruby
+gem "ask-guests"
+```
+
+In a Rails app, run the installer:
+
+```bash
+bin/rails generate ask:guests:install
+```
+
+It creates the `guest_sessions` migration and an initializer, and prints
+the model and controller wiring.
+
+## Core usage
+
+```ruby
+Ask::Guests.configure do |config|
+  config.secret = ENV.fetch("GUEST_TOKEN_SECRET")
+  config.store = Ask::Guests::Stores::Memory.new
+  config.policies = [Ask::Guests::Budget::TurnLimit.new(per_day: 40)]
+  config.retention = 14 * 24 * 60 * 60 # seconds
+end
+
+# Mint a session and hand the visitor a token (put it in a cookie yourself,
+# or use the Rails adapter):
+session = Ask::Guests.store.create(metadata: {ip_address: request.ip})
+token = Ask::Guests::Token.sign(session.id)
+cookies[:guest] = token
+
+# Resolve a returning visitor:
+id = Ask::Guests::Token.verify(cookies[:guest])   # => session id or nil
+session = Ask::Guests.store.find(id)              # => Session or nil
+```
+
+### Metering AI usage
+
+The budget is checked before a turn and recorded after — works with any
+agent runtime, including ask-agent streams:
+
+```ruby
+budget = Ask::Guests.budget
+
+unless budget.allowed?(guest_session)
+  return render_quota_exceeded   # "create an account to keep going"
+end
+
+response = agent.run(prompt)
+budget.record!(guest_session, turns: 1, tokens: response.input_tokens + response.output_tokens)
+```
+
+Policies compose — a guest is allowed only while every policy has budget
+left, and counters roll over daily with no scheduled work:
+
+```ruby
+config.policies = [
+  Ask::Guests::Budget::TurnLimit.new(per_day: 40),
+  Ask::Guests::Budget::TokenQuota.new(per_day: 10_000)
+]
+```
+
+### Claiming on sign-up
+
+Register one handler per owned model. Handlers run inside the claim's
+transaction, after the session has been re-read under a lock — a replayed
+cookie or double-submit can never claim twice:
+
+```ruby
+Ask::Guests.claimable(:work_requests) do |session, owner|
+  WorkRequest.where(guest_session_id: session.id)
+    .update_all(account_id: owner.account_id, account_user_id: owner.id, guest_session_id: nil)
+end
+
+Ask::Guests::Claim.new(session: guest_session, owner: account_user).call # => true
+```
+
+### Retention
+
+```ruby
+Ask::Guests.sweep.call # destroys unclaimed sessions inactive past retention
+```
+
+## Rails
+
+```ruby
+# app/models/guest_session.rb
+class GuestSession < Ask::Guests::ActiveRecord::SessionBase
+  self.table_name = "guest_sessions"
+  has_many :work_requests, foreign_key: :guest_session_id, dependent: :destroy
+end
+
+# config/initializers/ask_guests.rb
+Ask::Guests.configure do |config|
+  config.secret = Rails.application.secret_key_base
+  config.store = Ask::Guests::ActiveRecord::SessionStore.new(model: GuestSession)
+  config.policies = [Ask::Guests::Budget::TurnLimit.new(per_day: 40)]
+end
+```
+
+Controllers:
+
+```ruby
+class WorkRequestsController < ApplicationController
+  include Ask::Guests::Rails::Controller
+
+  allow_guest_access                  # resume the cookie on every request
+  before_action :require_visitor      # user or guest — never nobody
+end
+```
+
+Views get `guest_session?` and `current_guest_session` as helpers.
+
+Claim on authentication (Devise shown; any auth works):
+
+```ruby
+class Users::RegistrationsController < Devise::RegistrationsController
+  include Ask::Guests::Rails::ClaimOnAuthentication
+
+  after_action :claim_guest_session, only: :create
+
+  private
+
+  def guest_claim_owner = current_user.account_users.first
+end
+```
+
+Schedule the sweep (`config/recurring.yml` for Solid Queue):
+
+```yaml
+production:
+  guests_sweep:
+    class: "Ask::Guests::Rails::SweepJob"
+    schedule: every day at 4am
+```
+
+Destroying a session destroys its row, so associations declared with
+`dependent: :destroy` sweep everything the guest owned.
+
+## Custom stores
+
+Implement `Ask::Guests::Stores::Base` (`create`, `find`, `update`,
+`destroy`, `sweep_stale`, and optionally `lock`/`transaction`) and point
+`config.store` at it. Stores return `Ask::Guests::Session` value objects
+and treat ids as opaque strings.
+
+## Hard-won details
+
+- **Budget is checked before anything is persisted** — a rejected turn
+  leaves no trace, so "create an account to continue" is honest.
+- **Capabilities stay server-side.** Metering bounds cost; what a guest
+  *cannot do* (submit work, trigger notifications) belongs in your tool
+  implementations, not the prompt.
+- **`config.secret` rotation** invalidates outstanding guest cookies —
+  visitors simply start fresh sessions.
+- **Touch throttling**: `last_seen_at` is written at most once per
+  `touch_interval` (default 300s) so page views don't write per request.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test
+```
+
+## License
+
+MIT.

data/lib/ask/guests/active_record/json_value.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ask
+  module Guests
+    module ActiveRecord
+      # Adapter-independent JSON attribute type.
+      #
+      # ActiveRecord's built-in +:json+ attribute type resolves against the
+      # database adapter at class-definition time (so the model cannot even
+      # be loaded before a connection exists, and behavior differs between
+      # PostgreSQL jsonb and SQLite text). This type does the same job with
+      # deterministic behavior everywhere:
+      #
+      #   * reads Hash (PostgreSQL jsonb) as-is
+      #   * parses String (SQLite text) into a Hash
+      #   * writes a JSON string
+      class JsonValue < ActiveModel::Type::Value
+        def type
+          :json
+        end
+
+        def cast(value)
+          normalize(value)
+        end
+
+        def deserialize(value)
+          normalize(value)
+        end
+
+        def serialize(value)
+          normalize(value).to_json
+        end
+
+        private
+
+        def normalize(value)
+          case value
+          when nil then nil
+          when String then parse(value)
+          else value
+          end
+        end
+
+        def parse(string)
+          return nil if string.strip.empty?
+
+          JSON.parse(string)
+        rescue JSON::ParserError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/ask/guests/active_record/session_base.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Ask
+  module Guests
+    module ActiveRecord
+      # Abstract ActiveRecord model for guest sessions. Subclass it in the
+      # host app (usually via the install generator), mapping it to the
+      # table created by the migration:
+      #
+      #   class GuestSession < Ask::Guests::ActiveRecord::SessionBase
+      #     self.table_name = "guest_sessions"
+      #     has_many :work_requests, foreign_key: :guest_session_id, dependent: :destroy
+      #   end
+      #
+      # Expected columns:
+      #   counters     - json/jsonb, daily usage counters ("{}" default)
+      #   metadata     - json/jsonb, free-form host data ("{}" default)
+      #   last_seen_at - datetime, updated on visitor activity
+      #   converted_at - datetime, set on claim; NULL means still a guest
+      #   owner_type   - string, polymorphic owner set on claim
+      #   owner_id     - bigint, polymorphic owner set on claim
+      class SessionBase < ::ActiveRecord::Base
+        self.abstract_class = true
+
+        # The gem owns these columns' semantics; use the adapter-independent
+        # JSON type so PostgreSQL json/jsonb and SQLite text columns behave
+        # identically (and the model loads without a database connection).
+        attribute :counters, JsonValue.new, default: {}
+        attribute :metadata, JsonValue.new, default: {}
+
+        belongs_to :owner, polymorphic: true, optional: true
+
+        def converted?
+          !converted_at.nil?
+        end
+
+        def unclaimed?
+          !converted?
+        end
+
+        # @return [Ask::Guests::Session]
+        def to_guest_session
+          Guests::Session.new(
+            id: id,
+            created_at: created_at,
+            last_seen_at: last_seen_at,
+            converted_at: converted_at,
+            owner_type: owner_type,
+            owner_id: owner_id,
+            counters: counters || {},
+            metadata: metadata || {}
+          )
+        end
+
+        # Writes a value object's state back onto this record (without
+        # saving). Used by SessionStore#update.
+        def apply_guest_session(session)
+          self.counters = session.counters
+          self.metadata = session.metadata
+          self.last_seen_at = session.last_seen_at
+          self.converted_at = session.converted_at
+          self.owner_type = session.owner_type
+          self.owner_id = session.owner_id
+          self
+        end
+      end
+    end
+  end
+end

data/lib/ask/guests/active_record/session_store.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Ask
+  module Guests
+    module ActiveRecord
+      # ActiveRecord-backed session store.
+      #
+      #   class GuestSession < Ask::Guests::ActiveRecord::SessionBase
+      #     self.table_name = "guest_sessions"
+      #     has_many :work_requests, foreign_key: :guest_session_id, dependent: :destroy
+      #   end
+      #
+      #   Ask::Guests.configure do |config|
+      #     config.store = Ask::Guests::ActiveRecord::SessionStore.new(model: GuestSession)
+      #   end
+      #
+      # Destroying a session destroys the record, so host associations
+      # declared with +dependent: :destroy+ sweep owned records too.
+      class SessionStore < Stores::Base
+        attr_reader :model
+
+        # @param model [Class] an ActiveRecord model class with the columns
+        #   documented on SessionBase
+        def initialize(model:)
+          @model = model
+        end
+
+        def create(attributes = {})
+          attributes = attributes.to_h.transform_keys(&:to_sym)
+          now = Guests.configuration.now
+          record = model.new(
+            counters: attributes[:counters] || {},
+            metadata: attributes[:metadata] || {},
+            last_seen_at: attributes[:last_seen_at] || now,
+            created_at: attributes[:created_at] || now
+          )
+          record.id = attributes[:id] if attributes[:id]
+          record.save!
+          record.to_guest_session
+        end
+
+        def find(id)
+          return nil if id.nil?
+
+          model.find_by(id: id)&.to_guest_session
+        end
+
+        # Re-reads the session with a row lock where the database supports
+        # it, for race-safe claiming.
+        def lock(id)
+          return nil if id.nil?
+
+          scope = model.lock
+          scope.find_by(id: id)&.to_guest_session
+        end
+
+        def update(session)
+          record = model.find_by(id: session.id)
+          return session if record.nil?
+
+          record.apply_guest_session(session)
+          record.save!
+          session
+        end
+
+        def destroy(session)
+          model.find_by(id: session.id)&.destroy
+          session
+        end
+
+        def sweep_stale(before:)
+          destroyed = 0
+          stale_scope(before).find_each do |record|
+            record.destroy
+            destroyed += 1
+          end
+          destroyed
+        end
+
+        def transaction(&block)
+          model.transaction(&block)
+        end
+
+        def supports_transactions?
+          true
+        end
+
+        private
+
+        def stale_scope(before)
+          model.where(converted_at: nil)
+            .where("COALESCE(last_seen_at, created_at) < ?", before)
+        end
+      end
+    end
+  end
+end

data/lib/ask/guests/budget/policy.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Ask
+  module Guests
+    class Budget
+      # Base class for usage policies. A policy owns one counter key (for
+      # example "turns" or "tokens") and a daily limit for it.
+      #
+      # Subclasses implement +counter_key+, +limit+, and +amount_for+.
+      class Policy
+        # @return [String] counter name on the session
+        def counter_key
+          raise NotImplementedError
+        end
+
+        # @return [Integer, Float::INFINITY] daily limit
+        def limit
+          raise NotImplementedError
+        end
+
+        # @return [Integer] how much this usage costs in counter units
+        def amount_for(turns:, tokens:)
+          raise NotImplementedError
+        end
+
+        # @return [Integer, Float] remaining budget for today
+        def remaining(session, today)
+          value = session.counter_value(counter_key, today)
+          [limit - value, 0].max
+        end
+
+        def record!(session, turns:, tokens:, today:)
+          amount = amount_for(turns: turns, tokens: tokens)
+          return session if amount.to_i.zero?
+
+          count = session.counter_value(counter_key, today) + amount.to_i
+          session.set_counter!(counter_key, count, today)
+        end
+      end
+    end
+  end
+end

data/lib/ask/guests/budget/token_quota.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Ask
+  module Guests
+    class Budget
+      # Limits tokens per day, for apps that meter actual consumption
+      # (input + output tokens) instead of turns.
+      #
+      #   Budget::TokenQuota.new(per_day: 10_000)
+      class TokenQuota < Policy
+        attr_reader :per_day
+
+        def initialize(per_day:)
+          super()
+          @per_day = per_day.to_i
+        end
+
+        def counter_key = "tokens"
+        def limit = per_day
+        def amount_for(turns:, tokens:) = tokens
+      end
+    end
+  end
+end

data/lib/ask/guests/budget/turn_limit.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Ask
+  module Guests
+    class Budget
+      # Limits agent turns per day. One "turn" is one agent run — the unit
+      # Kawibot meters.
+      #
+      #   Budget::TurnLimit.new(per_day: 40)
+      class TurnLimit < Policy
+        attr_reader :per_day
+
+        def initialize(per_day:)
+          super()
+          @per_day = per_day.to_i
+        end
+
+        def counter_key = "turns"
+        def limit = per_day
+        def amount_for(turns:, tokens:) = turns
+      end
+    end
+  end
+end

data/lib/ask/guests/budget/unlimited.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Ask
+  module Guests
+    class Budget
+      # No limits — the default policy. Useful for development and for apps
+      # that meter elsewhere.
+      class Unlimited < Policy
+        def counter_key = "unlimited"
+        def limit = Float::INFINITY
+        def amount_for(turns:, tokens:) = 0
+        def remaining(session, today) = Float::INFINITY
+      end
+    end
+  end
+end

data/lib/ask/guests/budget.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Ask
+  module Guests
+    # Meters guest usage against one or more policies and records usage
+    # afterwards. Policies are checked collectively: a guest is allowed only
+    # while every policy has budget remaining.
+    #
+    #   budget = Ask::Guests.budget
+    #   budget.allowed?(session) # => true/false
+    #   budget.remaining(session) # => Integer (minimum across policies)
+    #   budget.record!(session, turns: 1, tokens: 850)
+    #
+    # Counters live on the session and roll over daily, so "per day" limits
+    # reset without any scheduled work.
+    class Budget
+      attr_reader :policies, :store
+
+      def initialize(policies: nil, store: Guests.store, clock: Guests.configuration.clock)
+        @policies = normalize(policies)
+        @store = store
+        @clock = clock
+      end
+
+      # @return [Boolean] true while every policy has budget left
+      def allowed?(session)
+        return true if session.nil?
+
+        policies.all? { |policy| policy.remaining(session, today) > 0 }
+      end
+
+      # Minimum remaining budget across policies (Float::INFINITY when no
+      # policy limits usage).
+      def remaining(session)
+        return Float::INFINITY if session.nil?
+
+        policies.map { |policy| policy.remaining(session, today) }.min
+      end
+
+      # Records usage, persists the session through the store, and returns it.
+      def record!(session, turns: 0, tokens: 0)
+        return session if session.nil?
+
+        policies.each { |policy| policy.record!(session, turns: turns, tokens: tokens, today: today) }
+        store.update(session)
+        session
+      end
+
+      def unlimited?
+        policies.all? { |policy| policy.remaining(Session.new(id: "probe"), today) == Float::INFINITY }
+      end
+
+      private
+
+      def normalize(policies)
+        case policies
+        when nil then [Budget::Unlimited.new]
+        when Array then policies
+        else [policies]
+        end
+      end
+
+      def today
+        @clock.call.utc.strftime("%Y-%m-%d")
+      end
+    end
+  end
+end