samagotchi 0.103.0 → 0.104.0

data/lib/samagotchi/testing/waiting.rb

@@ -5,12 +5,71 @@ require_relative "../process_group"
 module Samagotchi
   module Testing
     # Waiting with a deadline, for a test that waits on a thread or a
-    # process (Helpers has them).
+    # process (Helpers has them). Every deadline is the given +timeout+ ×
+    # Waiting.time_scale (SPEC_TIME_SCALE, CI sets 2): a slow runner gets
+    # more headroom, a fast one never waits longer than its condition takes.
     module Waiting
+      # A wait whose deadline passed: its message names what it waited for
+      # (Waiting.timed_out_message).
+      class TimedOut < StandardError; end
+
+      # The most of a +seen:+ value's inspect a message shows.
+      SEEN_LIMIT = 300
+
+      class << self
+        # SPEC_TIME_SCALE as a Float, at least 1 (unset or empty: 1). A value
+        # that isn't a number gives 1 and one warning. Read per call.
+        def time_scale
+          raw = ENV.fetch("SPEC_TIME_SCALE", "").strip
+          return 1.0 if raw.empty?
+
+          [Float(raw), 1.0].max
+        rescue ArgumentError
+          unless @warned_scale
+            @warned_scale = true
+            warn("SPEC_TIME_SCALE=#{raw.inspect} is not a number: waiting with scale 1")
+          end
+          1.0
+        end
+
+        # +timeout+ s scaled: the deadline a helper waits for.
+        def scaled(timeout, scale = time_scale) = timeout * scale
+
+        # How long a wait took to give up: "5 s", or with a scale
+        # "10.0 s (5 s × SPEC_TIME_SCALE 2)".
+        def waited(timeout, scale = time_scale)
+          return "#{timeout} s" if scale == 1
+
+          "#{scaled(timeout, scale).round(3).to_f} s (#{timeout} s × SPEC_TIME_SCALE #{number(scale)})"
+        end
+
+        # The one failure text of wait_for, join! and pop!:
+        # "timed out after 5 s waiting for <what>", then "; last saw: <value>"
+        # when +seen+ (a callable) is given, its value's inspect cut to
+        # SEEN_LIMIT chars.
+        def timed_out_message(what, timeout, scale: time_scale, seen: nil)
+          message = "timed out after #{waited(timeout, scale)} waiting for #{what}"
+          seen ? "#{message}; last saw: #{seen_text(seen)}" : message
+        end
+
+        private
+
+        def number(value) = value == value.to_i ? value.to_i.to_s : value.to_s
+
+        def seen_text(seen)
+          text = seen.call.inspect
+          text.length > SEEN_LIMIT ? "#{text[0, SEEN_LIMIT]}…" : text
+        rescue StandardError => e
+          "(raised #{e.class}: #{e.message})"
+        end
+      end
+
       # The block's value once truthy, polled every +interval+ s; after
-      # +timeout+ s its last (falsy) value.
+      # +timeout+ s (scaled) its last (falsy) value. For a wait whose
+      # timeout is fine (a bounded best-effort wait); a wait that must hold
+      # is #wait_for.
       def wait_until(timeout: 5, interval: 0.01)
-        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + Waiting.scaled(timeout)
         until (value = yield)
           return yield if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
 
@@ -19,15 +78,39 @@ module Samagotchi
         value
       end
 
-      # #wait_until, raising "timed out after N s waiting for <what>" when
-      # the time runs out: for a wait no check follows.
-      def wait_until!(what, timeout: 5, interval: 0.01, &)
-        wait_until(timeout: timeout, interval: interval, &) || raise("timed out after #{timeout} s waiting for #{what}")
+      # Polls the block every +interval+ s until it returns truthy and
+      # returns that value. After +timeout+ s (scaled) it raises
+      # Waiting::TimedOut naming +what+ ("timed out after 5 s waiting for
+      # <what>"); +seen+ (a callable) adds what it last saw, since a falsy
+      # block value tells nothing.
+      def wait_for(what, timeout: 5, interval: 0.01, seen: nil, &)
+        wait_until(timeout: timeout, interval: interval, &) ||
+          raise(TimedOut, Waiting.timed_out_message(what, timeout, seen: seen))
+      end
+
+      # Thread#join with a deadline (scaled): a thread that never ends fails
+      # the test with "<what> to finish" named, not after a suite-wide guard.
+      # Raises what the thread raised, as #join does.
+      # @return [Thread]
+      def join!(thread, what, timeout: 5)
+        thread.join(Waiting.scaled(timeout)) || raise(TimedOut, Waiting.timed_out_message("#{what} to finish", timeout))
+      end
+
+      # Queue#pop with a deadline (scaled), for a queue that never carries
+      # nil: nothing pushed in time fails with +what+ named. A gate a stubbed
+      # lib thread waits on while the test works takes a longer +timeout+
+      # (30): it only has to end a hang, never cut a slow test short.
+      # @return the value popped.
+      def pop!(queue, what, timeout: 5)
+        value = queue.pop(timeout: Waiting.scaled(timeout))
+        raise(TimedOut, Waiting.timed_out_message(what, timeout)) if value.nil?
+
+        value
       end
 
       # Whether no process +pid+ is left (a killed grandchild is reaped a
-      # moment later: wait_until { process_gone?(pid) }). One that isn't
-      # ours to signal is still there (ProcessGroup.alive?).
+      # moment later: wait_for("pid gone") { process_gone?(pid) }). One that
+      # isn't ours to signal is still there (ProcessGroup.alive?).
       def process_gone?(pid) = !ProcessGroup.alive?(pid)
     end
   end

data/lib/samagotchi/tools/task_runtime.rb

@@ -99,9 +99,10 @@ module Samagotchi
       # status. Only while this chi runs. A record a refresh finished in
       # between (failed, no exit code) is corrected; a stopped task (its
       # stop flag on disk) is left as task_stop records it.
-      # The thread is named EXIT_STATUS_THREAD (a spec joins them before it
-      # removes the tasks' folder) here, before it returns: named from
-      # inside, a thread not yet scheduled was missed by that join.
+      # The thread is named EXIT_STATUS_THREAD (a spec joins them with
+      # #quiesce! before it removes the tasks' folder) here, before it
+      # returns: named from inside, a thread not yet scheduled was missed by
+      # that join.
       # @return [Thread]
       def record_exit_status(waiter, path, task_id:)
         # Absolute now: safe against a later chdir.
@@ -132,6 +133,19 @@ module Samagotchi
       # record_exit_status's threads' name.
       EXIT_STATUS_THREAD = "task_exit_status"
 
+      # Joins every live EXIT_STATUS_THREAD, for up to +timeout+ s in all: a
+      # spec calls it (with_task_dir) after stopping its tasks and before it
+      # removes their folder, which a recorder may still write into. chi
+      # itself doesn't call it.
+      # @return [Array<Thread>] the ones still alive after +timeout+ (empty
+      #   when quiet)
+      def quiesce!(timeout: 5)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        threads = Thread.list.select { |thread| thread.name == EXIT_STATUS_THREAD && thread != Thread.current }
+        threads.each { |thread| thread.join([deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC), 0].max) }
+        threads.select(&:alive?)
+      end
+
       # Reasons a refresh finishes a record with when it read no exit code.
       MISSING_CODE_REASONS = ["process_ended_without_exit_code", NOT_CHIS_PROCESS].freeze
 

data/lib/samagotchi/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Samagotchi
-  VERSION = "0.103.0"
+  VERSION = "0.104.0"
   # Sent as the User-Agent of every HTTP request chi makes.
   USER_AGENT = "chi/#{VERSION}"
 end

data/lib/samagotchi/web/app.rb

@@ -53,6 +53,8 @@ require_relative "editor"
 require_relative "../message_parts"
 require_relative "session_summary"
 require_relative "session_access_routes"
+require_relative "principal"
+require_relative "participant_access"
 require_relative "../log"
 require_relative "../paths"
 require_relative "../redacted_inspect"
@@ -70,6 +72,7 @@ module Samagotchi
       # @lan holds the LAN access token.
       include RedactedInspect
       include SessionAccessRoutes
+      include ParticipantAccess
 
       DEFAULT_HOST = BridgeClient::HOST
       BRIDGE_WAIT_TIMEOUT = 10.0
@@ -83,7 +86,11 @@ module Samagotchi
       IMAGE_TYPES = { "png" => "image/png", "jpg" => "image/jpeg", "jpeg" => "image/jpeg", "gif" => "image/gif",
                       "webp" => "image/webp" }.freeze
 
-      # POST /stop waits this long for the worker to let go of the session.
+      # POST /stop waits this long for the worker to let go of the session
+      # when the body names no wait (the page's Stop: it shows the stop at
+      # once, and a Rack thread isn't held for it). A CLI through --remote
+      # sends its own, SessionManager::STOP_WAIT at most, so chi sessions
+      # stop waits as long as here.
       STOP_WAIT_SECONDS = 2.0
 
       # GET /api/events: a `: ping` this often while idle, a queue this deep
@@ -126,13 +133,16 @@ module Samagotchi
       #   the address the server also listens on and its access token (a
       #   String, or a Web::Token::Source that follows the file); nil:
       #   loopback only, no token
+      # @param grants [Grants, nil] the participants' grants (default: the
+      #   store next to +state_dir+, Grants.path)
       def initialize(manager: nil, session_class: nil, state_dir: nil, public_dir: nil,
                      bridge_wait_timeout: BRIDGE_WAIT_TIMEOUT, markdown: false, view: Config::BY_KEY["web.view"].default, hub: nil,
                      annotate_presets: Config::BY_KEY["web.annotate_presets"].default,
                      editor: Config::BY_KEY["web.editor"].default,
                      events_heartbeat: EVENTS_HEARTBEAT, events_queue: EVENTS_QUEUE,
                      registry: nil, models_wait_timeout: MODELS_WAIT_TIMEOUT, lan: nil,
-                     working_set: Config::BY_KEY["web.working_set"].default, wait_poll_interval: ReplyWait::POLL_INTERVAL)
+                     working_set: Config::BY_KEY["web.working_set"].default, wait_poll_interval: ReplyWait::POLL_INTERVAL,
+                     grants: nil)
         @manager = manager || SessionManager
         @registry = registry
         @registry_given = !registry.nil?
@@ -156,6 +166,7 @@ module Samagotchi
         @refused_mutex = Mutex.new
         @refused_logged = {}
         @wait_poll_interval = wait_poll_interval
+        init_participant_access(grants, state_dir)
       end
 
       def call(env)
@@ -168,47 +179,63 @@ module Samagotchi
       private
 
       # The routes, first match wins: a handler takes the request and the
-      # path's captures (the session id, an image's name). A :session route
-      # runs in #session_route: an ArgumentError is its unknown session.
+      # path's captures (the session id, an image's name). The fourth column
+      # is who may use the route (ROUTE_PERMISSIONS, checked against the
+      # request's Principal): :owner, or :participant for one a participant
+      # may use too, its handler answering them as theirs (the participant
+      # page, the trimmed info, the filtered show; docs/internals/
+      # participants.md). A :session route runs in #session_route: an
+      # ArgumentError is its unknown session.
+      ROUTE_PERMISSIONS = %i[owner participant].freeze
       ROUTES = [
-        ["GET", %r{\A/(?:index\.html)?\z}, :serve_index],
-        ["GET", %r{\A/api/sessions\z}, :handle_list],
-        ["POST", %r{\A/api/sessions\z}, :handle_create],
-        ["GET", %r{\A/api/sessions/resolve\z}, :handle_resolve],
-        ["GET", %r{\A/api/sessions/summaries\z}, :handle_summaries],
-        ["GET", %r{\A/api/info\z}, :handle_info],
-        ["GET", %r{\A/api/models\z}, :handle_models],
-        ["GET", %r{\A/api/history\z}, :handle_history],
-        ["GET", %r{\A/api/events\z}, :handle_events],
-        ["POST", %r{\A/api/render\z}, :handle_render],
-        ["GET", %r{\A/api/sessions/([^/]+)/stream\z}, :handle_stream],
-        ["GET", %r{\A/api/sessions/([^/]+)/output\z}, :handle_output, :session],
-        ["POST", %r{\A/api/sessions/([^/]+)/cancel\z}, :handle_cancel, :session],
-        ["POST", %r{\A/api/sessions/([^/]+)/tasks/([^/]+)/stop\z}, :handle_task_stop, :session],
-        ["POST", %r{\A/api/sessions/([^/]+)/turn/([^/]+)/dequeue\z}, :handle_dequeue_turn, :session],
-        ["POST", %r{\A/api/sessions/([^/]+)/stop\z}, :handle_stop, :session],
-        ["POST", %r{\A/api/sessions/([^/]+)/restart\z}, :handle_restart, :session],
-        ["POST", %r{\A/api/sessions/([^/]+)/archive\z}, :handle_archive, :session],
-        ["POST", %r{\A/api/sessions/([^/]+)/unarchive\z}, :handle_unarchive, :session],
-        ["POST", %r{\A/api/sessions/([^/]+)/turn\z}, :handle_turn, :session],
-        ["POST", %r{\A/api/sessions/([^/]+)/wait/prepare\z}, :handle_wait_prepare, :session],
-        ["POST", %r{\A/api/sessions/([^/]+)/wait\z}, :handle_wait, :session],
-        ["POST", %r{\A/api/sessions/([^/]+)/notes\z}, :handle_notes, :session],
-        ["POST", %r{\A/api/sessions/([^/]+)/wake\z}, :handle_wake, :session],
-        ["GET", %r{\A/api/sessions/([^/]+)/worker\z}, :handle_worker, :session],
-        ["POST", %r{\A/api/sessions/([^/]+)/answer\z}, :handle_question_answer],
-        ["POST", %r{\A/api/sessions/([^/]+)/question/dismiss\z}, :handle_question_dismiss],
-        ["POST", %r{\A/api/sessions/([^/]+)/command\z}, :handle_command, :session],
-        ["POST", %r{\A/api/sessions/([^/]+)/images\z}, :handle_image_upload],
-        ["GET", %r{\A/api/sessions/([^/]+)/images/([^/]+)\z}, :handle_image],
-        ["GET", %r{\A/api/sessions/([^/]+)/context\z}, :handle_context_list, :session],
-        ["GET", %r{\A/api/sessions/([^/]+)/context/([^/]+)\z}, :handle_context_show, :session],
-        ["POST", %r{\A/api/sessions/([^/]+)/context\z}, :handle_context_add, :session],
-        ["POST", %r{\A/api/sessions/([^/]+)/context/([^/]+)/push\z}, :handle_context_push, :session],
-        ["DELETE", %r{\A/api/sessions/([^/]+)/context/([^/]+)\z}, :handle_context_delete, :session],
-        ["GET", %r{\A/api/sessions/([^/]+)/working_set\z}, :handle_working_set, :session],
-        ["GET", %r{\A/api/sessions/([^/]+)\z}, :handle_show, :session],
-        ["DELETE", %r{\A/api/sessions/([^/]+)\z}, :handle_delete, :session]
+        ["GET", %r{\A/(?:index\.html)?\z}, :serve_index, :participant],
+        ["GET", %r{\A/api/sessions\z}, :handle_list, :owner],
+        ["POST", %r{\A/api/sessions\z}, :handle_create, :owner],
+        ["GET", %r{\A/api/sessions/resolve\z}, :handle_resolve, :owner],
+        ["GET", %r{\A/api/sessions/summaries\z}, :handle_summaries, :owner],
+        ["GET", %r{\A/api/info\z}, :handle_info, :participant],
+        ["GET", %r{\A/api/models\z}, :handle_models, :owner],
+        ["GET", %r{\A/api/history\z}, :handle_history, :owner],
+        ["GET", %r{\A/api/events\z}, :handle_events, :owner],
+        ["POST", %r{\A/api/render\z}, :handle_render, :owner],
+        ["GET", %r{\A/api/sessions/([^/]+)/stream\z}, :handle_stream, :owner],
+        ["GET", %r{\A/api/sessions/([^/]+)/output\z}, :handle_output, :owner, :session],
+        ["POST", %r{\A/api/sessions/([^/]+)/cancel\z}, :handle_cancel, :owner, :session],
+        ["POST", %r{\A/api/sessions/([^/]+)/tasks/([^/]+)/stop\z}, :handle_task_stop, :owner, :session],
+        ["POST", %r{\A/api/sessions/([^/]+)/turn/([^/]+)/dequeue\z}, :handle_dequeue_turn, :owner, :session],
+        ["POST", %r{\A/api/sessions/([^/]+)/stop\z}, :handle_stop, :owner, :session],
+        ["POST", %r{\A/api/sessions/([^/]+)/restart\z}, :handle_restart, :owner, :session],
+        ["POST", %r{\A/api/sessions/([^/]+)/archive\z}, :handle_archive, :owner, :session],
+        ["POST", %r{\A/api/sessions/([^/]+)/unarchive\z}, :handle_unarchive, :owner, :session],
+        ["POST", %r{\A/api/sessions/([^/]+)/turn\z}, :handle_turn, :owner, :session],
+        ["POST", %r{\A/api/sessions/([^/]+)/wait/prepare\z}, :handle_wait_prepare, :owner, :session],
+        ["POST", %r{\A/api/sessions/([^/]+)/wait\z}, :handle_wait, :owner, :session],
+        ["POST", %r{\A/api/sessions/([^/]+)/notes\z}, :handle_notes, :owner, :session],
+        ["POST", %r{\A/api/sessions/([^/]+)/wake\z}, :handle_wake, :owner, :session],
+        ["GET", %r{\A/api/sessions/([^/]+)/worker\z}, :handle_worker, :owner, :session],
+        ["POST", %r{\A/api/sessions/([^/]+)/exit\z}, :handle_exit, :owner, :session],
+        ["POST", %r{\A/api/sessions/([^/]+)/recap\z}, :handle_recap, :owner, :session],
+        ["GET", %r{\A/api/sessions/([^/]+)/stats\z}, :handle_stats, :owner, :session],
+        ["GET", %r{\A/api/sessions/([^/]+)/children/counts\z}, :handle_children_counts, :owner, :session],
+        ["GET", %r{\A/api/sessions/([^/]+)/turns/([^/]+)/records\z}, :handle_turn_records, :owner, :session],
+        ["POST", %r{\A/api/sessions/([^/]+)/answer\z}, :handle_question_answer, :owner],
+        ["POST", %r{\A/api/sessions/([^/]+)/question/dismiss\z}, :handle_question_dismiss, :owner],
+        ["POST", %r{\A/api/sessions/([^/]+)/command\z}, :handle_command, :owner, :session],
+        ["POST", %r{\A/api/sessions/([^/]+)/images\z}, :handle_image_upload, :owner],
+        ["GET", %r{\A/api/sessions/([^/]+)/images/([^/]+)\z}, :handle_image, :owner],
+        ["GET", %r{\A/api/sessions/([^/]+)/context\z}, :handle_context_list, :owner, :session],
+        ["GET", %r{\A/api/sessions/([^/]+)/context/([^/]+)\z}, :handle_context_show, :owner, :session],
+        ["POST", %r{\A/api/sessions/([^/]+)/context\z}, :handle_context_add, :owner, :session],
+        ["POST", %r{\A/api/sessions/([^/]+)/context/([^/]+)/push\z}, :handle_context_push, :owner, :session],
+        ["DELETE", %r{\A/api/sessions/([^/]+)/context/([^/]+)\z}, :handle_context_delete, :owner, :session],
+        ["GET", %r{\A/api/sessions/([^/]+)/working_set\z}, :handle_working_set, :owner, :session],
+        ["GET", %r{\A/api/sessions/([^/]+)/participants\z}, :handle_participants_list, :owner, :session],
+        ["POST", %r{\A/api/sessions/([^/]+)/participants\z}, :handle_participants_invite, :owner, :session],
+        ["DELETE", %r{\A/api/sessions/([^/]+)/participants\z}, :handle_participants_revoke, :owner, :session],
+        ["GET", %r{\A/api/participants\z}, :handle_participants_list, :owner],
+        ["DELETE", %r{\A/api/participants\z}, :handle_participants_revoke, :owner],
+        ["GET", %r{\A/api/sessions/([^/]+)\z}, :handle_show, :participant, :session],
+        ["DELETE", %r{\A/api/sessions/([^/]+)\z}, :handle_delete, :owner, :session]
       ].freeze
 
       def route(env)
@@ -216,13 +243,18 @@ module Samagotchi
         return forbidden unless local_host_header?(env)
         return cross_origin if cross_site?(env)
 
-        if @lan && !LOOPBACK_PEERS.include?(env["REMOTE_ADDR"].to_s)
-          denied = token_gate(req)
-          return denied if denied
-        end
+        principal, denied = token_gate(req)
+        return denied if denied
 
-        ROUTES.each do |verb, pattern, handler, kind|
+        # The principal the handlers read (#principal): never the body's.
+        env[PRINCIPAL_ENV] = principal
+        participant_seen(req, principal) unless principal.owner?
+        ROUTES.each do |verb, pattern, handler, permission, kind|
           next unless req.request_method == verb && (m = pattern.match(req.path_info))
+          # Before the permission: a participant learns nothing of another session.
+          return unknown_session(m.captures.first) if other_session?(principal, req.path_info, m.captures)
+          return not_permitted_for(req, principal) unless principal.permits?(permission)
+
           # Every /api/sessions/:id route: an id that isn't one (Session.valid_id?,
           # "..", a %2F) is an unknown session before any handler makes a path.
           # (/api/sessions/resolve and /summaries take no id.)
@@ -312,25 +344,57 @@ module Samagotchi
       TOKEN_COOKIE_ATTRIBUTES = "HttpOnly; SameSite=Lax; Path=/; Max-Age=34560000"
       REFUSED_LOG_INTERVAL = 60.0
 
+      # Where #route keeps the request's Principal for its handlers.
+      PRINCIPAL_ENV = "samagotchi.principal"
+      PAGE_PATHS = ["/", "/index.html"].freeze
+
+      # The request's Principal, as #route resolved it.
+      def principal(req) = req.env.fetch(PRINCIPAL_ENV)
+
       # LAN mode, a peer that isn't this machine (the peer is the socket's
       # address, REMOTE_ADDR: never X-Forwarded-For or req.ip, which trust
       # headers a phone could send): every route needs the access token, as
       # the chi_token cookie or an Authorization: Bearer header. The page
       # with ?token= trades it for the cookie and a 303 to itself without
       # it, so the token doesn't stay in the phone's history.
-      # @return [Array, nil] the response that refuses it, or nil to go on
+      # @return [Array(Principal, nil), Array(nil, Array)] the request's
+      #   principal (#principal_for), or the response that refuses it
       def token_gate(req)
+        principal = principal_for(req)
+        return [nil, grant_ended_response(req) || unauthorized(req)] if principal.nil?
+        # The cookie gets the token that was presented: the owner's, or the
+        # participant's grant's.
+        return [nil, token_redirect(req, req.env[GRANT_TOKEN_ENV] || current_token)] if token_trade?(req)
+
+        [principal, nil]
+      end
+
+      # Who the request is: the owner for a peer the gate doesn't ask (no
+      # LAN mode, or this machine's loopback) and for the access token (the
+      # page's ?token= on a trade, else the Bearer header or the cookie);
+      # a participant for a live grant's token (Grants, looked up only when
+      # no owner token was given); nil for anyone else.
+      # @return [Principal, nil]
+      def principal_for(req)
+        return Principal::OWNER unless token_required?(req)
+
         token = current_token
-        if req.get? && ["/", "/index.html"].include?(req.path_info) && req.params.key?("token")
-          return token_redirect(req, token) if token_match?(req.params["token"], token)
-        else
-          auth = req.get_header("HTTP_AUTHORIZATION").to_s[/\ABearer +(\S+)\z/, 1]
-          return nil if token_match?(auth, token) || token_match?(req.cookies[TOKEN_COOKIE], token)
-        end
+        given = token_trade?(req) ? [req.params["token"]] : [bearer_token(req), req.cookies[TOKEN_COOKIE]]
+        return Principal::OWNER if given.any? { |value| token_match?(value, token) }
 
-        unauthorized(req)
+        participant_principal(req, given.select { |value| Grants.token?(value) })
       end
 
+      def token_required?(req) = @lan && !LOOPBACK_PEERS.include?(req.get_header("REMOTE_ADDR").to_s)
+
+      # The page opened with ?token= (a gated request): its token is traded
+      # for the cookie, whatever else the request carries.
+      def token_trade?(req)
+        token_required?(req) && req.get? && PAGE_PATHS.include?(req.path_info) && req.params.key?("token")
+      end
+
+      def bearer_token(req) = req.get_header("HTTP_AUTHORIZATION").to_s[/\ABearer +(\S+)\z/, 1]
+
       def current_token
         token = @lan[:token]
         token.respond_to?(:current) ? token.current : token
@@ -417,6 +481,11 @@ module Samagotchi
         error_response(403, "cross_origin", "requests from other websites are refused")
       end
 
+      # A route the request's principal may not use (Principal#permits?).
+      def not_permitted
+        error_response(403, "not_permitted", "only the session's owner can do that")
+      end
+
       def forbidden
         names = @lan ? "127.0.0.1, [::1], localhost and #{@lan[:ip]}" : "127.0.0.1, [::1] and localhost"
         error_response(403, "forbidden", "only the host names #{names} are answered")
@@ -473,14 +542,17 @@ module Samagotchi
       # session_commands: the routes chi --remote needs
       # (SessionAccessRoutes::FEATURE); remote_attach: the ones a remote
       # attached TUI needs (ATTACH_FEATURE). lan: its LAN address, nil when it
-      # listens on loopback only.
-      def handle_info(_req)
+      # listens on loopback only. A participant gets app, version and
+      # features only (#participant_info).
+      def handle_info(req)
+        return participant_info unless principal(req).owner?
+
         json_response(200, { app: "chi-web", version: Samagotchi::VERSION, installed: @hub&.installed, pid: Process.pid,
-                             cwd: Dir.pwd, features: ["dir", "newest_workers", SessionAccessRoutes::FEATURE,
-                                                      SessionAccessRoutes::ATTACH_FEATURE],
-                             lan: @lan && @lan[:ip] })
+                             cwd: Dir.pwd, features: INFO_FEATURES, lan: @lan && @lan[:ip] })
       end
 
+      INFO_FEATURES = ["dir", "newest_workers", SessionAccessRoutes::FEATURE, SessionAccessRoutes::ATTACH_FEATURE].freeze
+
       # The models a new session can start on, spelled as chi spells them
       # elsewhere: bare for the default host (what default.model holds), and
       # host:model for another host. The default is the configured model, or
@@ -945,6 +1017,8 @@ module Samagotchi
       end
 
       def handle_show(req, id)
+        return participant_show(id) unless principal(req).owner?
+
         # The page's light re-reads: never the whole conversation.
         return handle_cards_read(id) if req.params["cards"] == "1"
         return handle_tail_read(req, id) if req.params["tail"] == "1"
@@ -1462,8 +1536,10 @@ module Samagotchi
         return refused if refused
 
         # no_interrupt: an attached TUI's --no-interrupt (chi --remote --attach).
+        # author: the principal's (nil for the owner), never the body's.
         result = SessionManager.deliver_turn(id, prompt: prompt.to_s, client_id: client_id, images: images,
                                                  delivery: delivery, no_interrupt: body["no_interrupt"] == true,
+                                                 author: principal(req).author,
                                                  state_dir: @state_dir, manager: @manager,
                                                  bridge: -> { live_bridge_client(id) })
         case result.status
@@ -1635,20 +1711,29 @@ module Samagotchi
         end
       end
 
-      # POST /api/sessions/:id/stop: 200 {status: "stopped", session_id,
-      # released}: released, whether the worker let go of the session
-      # within STOP_WAIT_SECONDS (chi sessions stop's two wordings); 409
+      # POST /api/sessions/:id/stop {wait?}: 200 {status: "stopped",
+      # session_id, released}: released, whether the worker let go of the
+      # session within the wait (STOP_WAIT_SECONDS, or the body's seconds up
+      # to SessionManager::STOP_WAIT: chi sessions stop's two wordings); 409
       # owned_by_tui.
-      def handle_stop(_req, id)
+      def handle_stop(req, id)
         # Bounded, so a Rack thread isn't held long; a worker still exiting
         # after it just means an immediate resume finds it (rare).
-        released = @manager.stop_session(id, state_dir: @state_dir, wait: STOP_WAIT_SECONDS)
+        released = @manager.stop_session(id, state_dir: @state_dir, wait: stop_wait(req))
         @hub&.touch(id)
         json_response(200, { status: "stopped", session_id: id, released: released == true })
       rescue SessionManager::OwnedByTUI => e
         owned_by_tui(e)
       end
 
+      # The body's wait (a number of seconds), capped at
+      # SessionManager::STOP_WAIT; STOP_WAIT_SECONDS without one.
+      def stop_wait(req)
+        body = parse_json(request_body(req, 4096))
+        wait = body["wait"] if body.is_a?(Hash)
+        wait.is_a?(Numeric) && wait.positive? ? [wait, SessionManager::STOP_WAIT].min : STOP_WAIT_SECONDS
+      end
+
       # POST /api/sessions/:id/restart: hand the session to a new worker on
       # the newest chi installed (SessionManager.restart_session). 200
       # {status: "restarted", session_id, from_version, version} (version nil:
@@ -1945,9 +2030,25 @@ module Samagotchi
           return [200, headers.merge("rack.hijack" => hijack), []]
         end
 
-        query = stream_query(req)
-        [200, headers, ProxyStreamBody.new(host: DEFAULT_HOST, port: bridge_port, session_id: id, query: query, headers: req.env,
-                                           server_running: @server_running)]
+        [200, headers, proxy_stream_body(id, req, bridge_port)]
+      end
+
+      # The one ProxyStreamBody both of #handle_stream's transports send:
+      # the session's Bridge stream, through the request principal's frame
+      # filter (#stream_filter).
+      def proxy_stream_body(id, req, port)
+        ProxyStreamBody.new(host: DEFAULT_HOST, port: port, session_id: id, query: stream_query(req), headers: req.env,
+                            server_running: stream_running(principal(req)), filter: stream_filter(principal(req)))
+      end
+
+      # What a principal's stream goes through on its way from the Bridge:
+      # nil, the raw bytes unchanged, for the owner (the only principal
+      # today). A filter is anything with #call(chunk) -> String (nil or
+      # "" sends nothing); see ProxyStreamBody.
+      def stream_filter(principal)
+        return nil if principal.owner?
+
+        raise ArgumentError, "no stream filter for a #{principal.kind} principal"
       end
 
       # GET /api/events: the session list as one SSE stream per tab. The
@@ -2007,10 +2108,10 @@ module Samagotchi
       # (WEBrick via rackup) has already sent the status line + headers, so
       # only body bytes go to the socket here.
       def sse_hijack(id, req, port)
+        # Made before the status line goes out: a principal with no filter
+        # is refused (#stream_filter), never streamed.
+        body = proxy_stream_body(id, req, port)
         lambda do |io|
-          query = stream_query(req)
-          body = ProxyStreamBody.new(host: DEFAULT_HOST, port: port, session_id: id, query: query, headers: req.env,
-                                     server_running: @server_running)
           body.each { |chunk| io.write(chunk) }
         rescue Errno::EPIPE, Errno::ECONNRESET, IOError
           nil # client went away — end the stream quietly
@@ -2068,6 +2169,8 @@ module Samagotchi
       end
 
       def serve_index(req)
+        return participant_page(principal(req)) unless principal(req).owner?
+
         path = File.join(@public_dir, "index.html")
         if File.file?(path)
           body = File.read(path).sub("<body>", "<body #{index_data_attributes(req)}>")
@@ -2614,15 +2717,20 @@ module Samagotchi
       # ends when the Bridge closes the stream or, as EventsBody, when the
       # server leaves :Running: rackup's WEBrick joins every request thread
       # before returning, and a read blocked on a quiet worker would hang
-      # Ctrl-C of chi web. The bytes go through unchanged.
+      # Ctrl-C of chi web. Without a +filter+ the bytes go through unchanged
+      # (the owner's stream); with one, each chunk read from the Bridge goes
+      # through it, and what it returns is sent.
       class ProxyStreamBody
         # @param headers [Hash] the request's Rack env; only its Last-Event-ID
         #   is kept (the env carries the token cookie, never held or inspected)
-        def initialize(host:, port:, session_id:, query:, headers:, server_running: -> { true })
+        # @param filter [#call, nil] chunk -> String (nil or "": nothing sent);
+        #   it sees the Bridge's reads as they come, not whole frames
+        def initialize(host:, port:, session_id:, query:, headers:, server_running: -> { true }, filter: nil)
           @client = BridgeClient.new(session_id: session_id, port: port, host: host)
           @query = query
           @last_event_id = headers["HTTP_LAST_EVENT_ID"]
           @server_running = server_running
+          @filter = filter
         end
 
         def each(&)
@@ -2630,7 +2738,12 @@ module Samagotchi
           # Last-Event-ID header over ?from_seq, and the reconnect URL carries a
           # stale initial cursor — without this the bridge would replay content
           # already delivered (duplicate bubbles).
-          @client.stream(query: @query, last_event_id: @last_event_id, running: @server_running, &)
+          return @client.stream(query: @query, last_event_id: @last_event_id, running: @server_running, &) unless @filter
+
+          @client.stream(query: @query, last_event_id: @last_event_id, running: @server_running) do |chunk|
+            out = @filter.call(chunk)
+            yield(out) unless out.nil? || out.empty?
+          end
         end
       end
     end