ask-guests 0.1.0

data/lib/ask/guests/claim.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Ask
+  module Guests
+    # Transfers everything a guest session owns to a real owner, exactly once.
+    #
+    #   Ask::Guests.claimable(:work_requests) do |session, owner|
+    #     WorkRequest.where(guest_session_id: session.id)
+    #       .update_all(owner_id: owner.id, guest_session_id: nil)
+    #   end
+    #
+    #   Claim.new(session: guest, owner: account_user).call # => true
+    #   Claim.new(session: guest, owner: account_user).call # => false (already claimed)
+    #
+    # Claiming is race-safe: the session is re-read under a lock (when the
+    # store supports it) inside the store's transaction, and the converted
+    # flag is written in the same transaction as the record transfer. A
+    # double-submit or a replayed cookie can never claim twice.
+    class Claim
+      def initialize(session:, owner:, store: Guests.store, claimables: Guests.claimables, clock: Guests.configuration.clock)
+        @session = session
+        @owner = owner
+        @store = store
+        @claimables = claimables
+        @clock = clock
+      end
+
+      def call
+        return false if @session.nil? || @owner.nil?
+        return false if @session.converted?
+
+        claimed = false
+        @store.transaction do
+          current = @store.lock(@session.id)
+          break if current.nil? || current.converted?
+
+          @claimables.each_value { |handler| handler.call(current, @owner) }
+          current.claimed_by!(@owner)
+          @store.update(current)
+
+          # Reflect the claim on the caller's object so it sees the new state.
+          @session.claimed_by!(@owner)
+          claimed = true
+        end
+        claimed
+      end
+    end
+  end
+end

data/lib/ask/guests/errors.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Ask
+  module Guests
+    class Error < StandardError; end
+
+    # Raised when a token must be signed or verified but no secret is
+    # configured.
+    class MissingSecret < Error
+      def initialize(message = "Ask::Guests.secret is not configured. Set it in Ask::Guests.configure.")
+        super
+      end
+    end
+  end
+end

data/lib/ask/guests/rails/claim_on_authentication.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Ask
+  module Guests
+    module Rails
+      # Claims the visitor's guest records right after they authenticate.
+      #
+      #   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   # or wherever records should land
+      #     end
+      #   end
+      #
+      # It is a no-op when there is no unclaimed guest cookie. On success it
+      # flashes the configured notice, deletes the guest cookie, and lets the
+      # authentication flow continue.
+      module ClaimOnAuthentication
+        extend ActiveSupport::Concern
+        include Ask::Guests::Rails::Controller
+
+        private
+
+        def claim_guest_session
+          session = resume_guest_session
+          return if session.nil? || session.converted?
+
+          # The host defines #guest_claim_owner (often on a shared auth
+          # concern); we only check for it so this module never shadows it.
+          unless respond_to?(:guest_claim_owner, true)
+            raise NotImplementedError,
+              "#{self.class} must implement #guest_claim_owner to use ClaimOnAuthentication"
+          end
+
+          owner = guest_claim_owner
+          return if owner.nil?
+
+          if Guests::Claim.new(session: session, owner: owner).call
+            flash[:notice] ||= Guests.configuration.claim_notice
+            end_guest_session
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ask/guests/rails/controller.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Ask
+  module Guests
+    module Rails
+      # Controller support for guest access.
+      #
+      #   class Kawifiles::WorkRequestsController < ApplicationController
+      #     include Ask::Guests::Rails::Controller
+      #
+      #     allow_guest_access
+      #     before_action :require_visitor
+      #   end
+      #
+      # +allow_guest_access+ resumes the visitor's guest session from its
+      # signed cookie on every request. +require_visitor+ guarantees an
+      # actor: an authenticated user when your controller reports one
+      # (it responds to +user_signed_in?+ or +signed_in?+), otherwise a
+      # guest session, created on the spot.
+      #
+      # The current session is available to views through +guest_session?+
+      # and +current_guest_session+ (registered as helper methods in Rails).
+      module Controller
+        extend ActiveSupport::Concern
+
+        included do
+          if respond_to?(:helper_method)
+            helper_method :guest_session?, :current_guest_session
+          end
+        end
+
+        class_methods do
+          # Resume the guest session from the cookie for the actions this is
+          # applied to. Pair with #require_visitor on guest-capable actions.
+          def allow_guest_access(**options)
+            before_action :resume_guest_session, **options
+          end
+        end
+
+        def current_guest_session
+          @current_guest_session
+        end
+
+        def guest_session?
+          !current_guest_session.nil?
+        end
+
+        private
+
+        # Guarantees an actor for the action: a signed-in user when the
+        # controller has one, otherwise a guest session.
+        def require_visitor
+          return if visitor_authenticated?
+
+          ensure_guest_session
+        end
+
+        def ensure_guest_session
+          resume_guest_session || start_guest_session!
+        end
+
+        # Returns the session from the signed cookie, or nil. Torn or
+        # tampered cookies and swept sessions resolve to nil — the next
+        # require_visitor mints a fresh session.
+        def resume_guest_session
+          return @current_guest_session if @current_guest_session
+
+          token = cookies.signed[Guests.configuration.cookie_name]
+          id = Guests::Token.verify(token, secret: Guests.secret)
+          return nil if id.nil?
+
+          session = Guests.store.find(id)
+          return nil if session.nil?
+
+          touch_guest_session(session)
+          @current_guest_session = session
+        end
+
+        def start_guest_session!
+          session = Guests.store.create(metadata: guest_request_metadata)
+          token = Guests::Token.sign(session.id, secret: Guests.secret)
+          cookies.signed.permanent[Guests.configuration.cookie_name] = {
+            value: token,
+            httponly: true,
+            same_site: :lax
+          }
+          @current_guest_session = session
+        end
+
+        # Retires the cookie. The converted session row stays for audit;
+        # a later anonymous visit starts a clean session.
+        def end_guest_session
+          cookies.delete(Guests.configuration.cookie_name)
+          @current_guest_session = nil
+        end
+
+        # Records activity, throttled to once per touch interval so ordinary
+        # page views don't write on every request.
+        def touch_guest_session(session)
+          now = Guests.configuration.now
+          last = session.last_seen_at
+          return session if last && (now - last) < Guests.configuration.touch_interval
+
+          session.touch_seen!(now)
+          Guests.store.update(session)
+          session
+        end
+
+        def visitor_authenticated?
+          if respond_to?(:user_signed_in?, true)
+            user_signed_in?
+          elsif respond_to?(:signed_in?, true)
+            signed_in?
+          else
+            false
+          end
+        end
+
+        def guest_request_metadata
+          metadata = {}
+          return metadata unless respond_to?(:request, true) && request
+
+          metadata[:ip_address] = request.remote_ip if request.respond_to?(:remote_ip)
+          metadata[:user_agent] = request.user_agent if request.respond_to?(:user_agent)
+          metadata
+        end
+      end
+    end
+  end
+end

data/lib/ask/guests/rails/sweep_job.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "active_job"
+
+module Ask
+  module Guests
+    module Rails
+      # Destroys stale unclaimed guest sessions on a schedule. Wire it into
+      # your recurring jobs config (Solid Queue, Sidekiq, etc.):
+      #
+      #   production:
+      #     guests_sweep:
+      #       class: "Ask::Guests::Rails::SweepJob"
+      #       schedule: every day at 4am
+      class SweepJob < ActiveJob::Base
+        queue_as { Ask::Guests.configuration.sweep_queue }
+
+        def perform
+          Ask::Guests.sweep.call
+        end
+      end
+    end
+  end
+end

data/lib/ask/guests/session.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Ask
+  module Guests
+    # A guest session value object: identity, lifecycle timestamps, the
+    # owner it was claimed by, and the counters used for usage metering.
+    #
+    # Stores return these objects (never raw rows); adapters translate
+    # between the value object and their persistence layer.
+    class Session
+      attr_reader :id, :created_at, :last_seen_at, :converted_at,
+        :owner_type, :owner_id, :counters, :metadata
+
+      def initialize(id:, created_at: nil, last_seen_at: nil, converted_at: nil,
+        owner_type: nil, owner_id: nil, counters: {}, metadata: {})
+        @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 = stringify(counters)
+        @metadata = stringify(metadata)
+      end
+
+      def converted?
+        !@converted_at.nil?
+      end
+
+      def unclaimed?
+        !converted?
+      end
+
+      # Marks the session as claimed by +owner+ (any object responding to
+      # +id+; polymorphic name used when available). The caller persists the
+      # session through the store.
+      def claimed_by!(owner)
+        @owner_type = owner_type_for(owner)
+        @owner_id = owner.id
+        @converted_at = @converted_at || Guests.configuration.now
+        self
+      end
+
+      def touch_seen!(at = Guests.configuration.now)
+        @last_seen_at = at
+        self
+      end
+
+      # Raw counter value for +name+ on +date+ ("YYYY-MM-DD"). Counters roll
+      # over daily: a value recorded on another day reads as 0.
+      def counter_value(name, date)
+        counter = @counters[name.to_s]
+        return 0 unless counter.is_a?(Hash)
+        return 0 unless counter["on"] == date.to_s
+
+        counter["count"].to_i
+      end
+
+      def set_counter!(name, count, date)
+        @counters[name.to_s] = {"count" => count.to_i, "on" => date.to_s}
+        self
+      end
+
+      def to_h
+        {
+          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
+
+      def ==(other)
+        other.is_a?(Session) && other.id.to_s == id.to_s
+      end
+      alias_method :eql?, :==
+
+      def hash
+        id.to_s.hash
+      end
+
+      private
+
+      def owner_type_for(owner)
+        if owner.respond_to?(:class) && owner.class.respond_to?(:polymorphic_name)
+          owner.class.polymorphic_name
+        else
+          owner.class.name
+        end
+      end
+
+      def stringify(hash)
+        (hash || {}).each_with_object({}) do |(key, value), result|
+          result[key.to_s] = value
+        end
+      end
+    end
+  end
+end

data/lib/ask/guests/stores/base.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Ask
+  module Guests
+    module Stores
+      # Persistence port for guest sessions. Implement this to plug in any
+      # backend (ActiveRecord ships in ask-guests/active_record), or use the
+      # in-memory store for tests and single-process apps.
+      #
+      # Implementations must return {Guests::Session} value objects and treat
+      # ids as opaque strings.
+      class Base
+        # @param attributes [Hash] initial session attributes
+        # @return [Session]
+        def create(attributes = {})
+          raise NotImplementedError
+        end
+
+        # @param id [String, Object]
+        # @return [Session, nil]
+        def find(id)
+          raise NotImplementedError
+        end
+
+        # Persists a session returned by {#create}/{#find} after mutation.
+        # @param session [Session]
+        # @return [Session]
+        def update(session)
+          raise NotImplementedError
+        end
+
+        # @param session [Session]
+        def destroy(session)
+          raise NotImplementedError
+        end
+
+        # Destroys unclaimed sessions last seen (or created) before the
+        # cutoff, along with anything they own.
+        # @param before [Time]
+        # @return [Integer] number of sessions destroyed
+        def sweep_stale(before:)
+          raise NotImplementedError
+        end
+
+        # Re-reads the session under a lock when the backend supports row
+        # locking. Defaults to a plain read; override for race-safe claiming.
+        # @return [Session, nil]
+        def lock(id)
+          find(id)
+        end
+
+        # Runs the block in a transaction when supported.
+        def transaction
+          yield
+        end
+
+        def supports_transactions?
+          false
+        end
+      end
+    end
+  end
+end

data/lib/ask/guests/stores/memory.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Ask
+  module Guests
+    module Stores
+      # In-memory session store. Useful for tests and single-process apps;
+      # sessions do not survive process restarts.
+      class Memory < Base
+        def initialize
+          @sessions = {}
+          @mutex = Mutex.new
+        end
+
+        def create(attributes = {})
+          attributes = attributes.transform_keys(&:to_sym)
+          id = (attributes.delete(:id) || SecureRandom.uuid).to_s
+          now = Guests.configuration.now
+
+          session = Session.new(
+            id: id,
+            created_at: now,
+            last_seen_at: now,
+            **attributes
+          )
+
+          @mutex.synchronize { @sessions[id] = session }
+          session
+        end
+
+        def find(id)
+          return nil if id.nil?
+
+          @mutex.synchronize { @sessions[id.to_s]&.dup }
+        end
+
+        def update(session)
+          @mutex.synchronize { @sessions[session.id.to_s] = session }
+          session
+        end
+
+        def destroy(session)
+          @mutex.synchronize { @sessions.delete(session.id.to_s) }
+          session
+        end
+
+        def sweep_stale(before:)
+          stale = @mutex.synchronize do
+            @sessions.values.select { |s| s.unclaimed? && last_activity(s) < before }
+          end
+          stale.each { |session| destroy(session) }
+          stale.size
+        end
+
+        # Test helper: number of stored sessions.
+        def size
+          @mutex.synchronize { @sessions.size }
+        end
+
+        private
+
+        def last_activity(session)
+          session.last_seen_at || session.created_at || Time.at(0)
+        end
+      end
+    end
+  end
+end

data/lib/ask/guests/sweep.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Ask
+  module Guests
+    # Deletes unclaimed guest sessions (and, via the store, everything they
+    # own) once they have been inactive for the configured retention period.
+    # Keeps anonymous traffic from accumulating storage and personal data
+    # forever.
+    #
+    #   Ask::Guests.sweep.call # => number of sessions destroyed
+    class Sweep
+      def initialize(store: Guests.store, retention: Guests.configuration.retention, clock: Guests.configuration.clock)
+        @store = store
+        @retention = retention
+        @clock = clock
+      end
+
+      def call
+        @store.sweep_stale(before: @clock.call - @retention)
+      end
+
+      # Cutoff time before which sessions are stale.
+      def cutoff
+        @clock.call - @retention
+      end
+    end
+  end
+end

data/lib/ask/guests/token.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "base64"
+require "openssl"
+
+module Ask
+  module Guests
+    # Signs and verifies guest session tokens with HMAC-SHA256.
+    #
+    # A token embeds only the session id — a random opaque value assigned by
+    # the store — and a signature. Sessions are looked up in the store by id,
+    # so a token for a swept or converted session simply resolves to nothing,
+    # and there is nothing to enumerate without the secret.
+    #
+    #   token = Token.sign(session.id, secret: "s3cr3t")
+    #   Token.verify(token, secret: "s3cr3t") # => "the-session-id"
+    #   Token.verify(tampered, secret: "s3cr3t") # => nil
+    module Token
+      SEPARATOR = "--"
+
+      class << self
+        def sign(id, secret: Guests.secret)
+          raise MissingSecret if secret.nil? || secret.empty?
+
+          payload = Base64.urlsafe_encode64(id.to_s, padding: false)
+          "#{payload}#{SEPARATOR}#{digest(payload, secret)}"
+        end
+
+        # Returns the session id for a valid token, nil for anything else
+        # (nil, empty, malformed, or wrong signature). Never raises for bad
+        # input — callers treat nil as "no session".
+        def verify(token, secret: Guests.secret)
+          return nil if token.nil? || secret.nil? || secret.empty?
+          return nil if token.to_s.empty?
+
+          payload, separator, signature = token.to_s.rpartition(SEPARATOR)
+          return nil if separator.empty? || payload.empty? || signature.empty?
+          return nil unless secure_compare(signature, digest(payload, secret))
+
+          Base64.urlsafe_decode64(payload)
+        rescue ArgumentError
+          nil
+        end
+
+        private
+
+        def digest(payload, secret)
+          OpenSSL::HMAC.hexdigest("SHA256", secret.to_s, payload)
+        end
+
+        def secure_compare(a, b)
+          return false unless a.bytesize == b.bytesize
+
+          OpenSSL.fixed_length_secure_compare(a, b)
+        end
+      end
+    end
+  end
+end

data/lib/ask/guests/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ask
+  module Guests
+    VERSION = "0.1.0"
+  end
+end