samagotchi 0.119.0 → 0.121.0

data/lib/samagotchi/web/app.rb

@@ -145,6 +145,8 @@ module Samagotchi
       #   with +public_url+ (the LAN one when both are set)
       # @param push [Push::Runtime, nil] Web Push for this run (PushRoutes);
       #   nil: off (no https public_url, or web.push.enabled false)
+      # @param start_dir [String] the folder chi web starts in (StartDir):
+      #   where a new session without a dir starts (nil: the cwd)
       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,
@@ -152,7 +154,8 @@ module Samagotchi
                      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,
-                     grants: nil, public_url: nil, public_token: nil, push: nil)
+                     grants: nil, public_url: nil, public_token: nil, push: nil, start_dir: nil)
+        @start_dir = start_dir
         @manager = manager || SessionManager
         @registry = registry
         @registry_given = !registry.nil?
@@ -490,7 +493,9 @@ module Samagotchi
 
       # The token a trade presents: the page's ?token=, or POST /api/token's
       # body's (read once): its token, or the token a one-time link code
-      # stands for (LinkCodes#redeem: used up here, whatever the gate says).
+      # stands for (LinkCodes#redeem: used up here, whatever the gate says,
+      # but for a grant's code bound to another identity: decision C, kept
+      # for the right one, and refused token_bound, #code_token).
       def traded_token(req)
         return req.params["token"] unless fragment_trade?(req)
 
@@ -501,17 +506,38 @@ module Samagotchi
                   else parse_json(raw)
                   end
           value = {} unless value.is_a?(Hash)
-          req.env[TRADED_TOKEN_ENV] = value.key?("code") ? code_token(value["code"]) : string_or_nil(value["token"])
+          req.env[TRADED_TOKEN_ENV] = value.key?("code") ? code_token(req, value["code"]) : string_or_nil(value["token"])
         end
       end
 
       def string_or_nil(value) = value.is_a?(String) ? value : nil
 
-      def code_token(code)
-        kind, token = @link_codes.redeem(code)
+      # A bound grant's code is checked before it is used up: presented by
+      # another identity, or not through the proxy, it stays (the one it was
+      # sent to can still open it) and the trade is refused token_bound.
+      def code_token(req, code)
+        kind, token = @link_codes.redeem(code) do |found_kind, found_token|
+          found_kind == :owner || code_identity_ok?(req, found_token)
+        end
         kind == :owner ? current_token : token
       end
 
+      def code_identity_ok?(req, token)
+        grant = @grants.lookup(token)
+        # No grant to check it against (deleted, left out of a newer store,
+        # a store that doesn't read): kept, the trade refused.
+        return false if grant.nil?
+        return true unless grant.identity
+
+        proxied = proxied?(req)
+        state, identity = proxied ? proxy_identity(req) : [:none, nil]
+        identity = nil unless state == :ok
+        return true if bound_ok?(grant, identity, proxied)
+
+        refuse_bound(req, grant, identity)
+        false
+      end
+
       TRADED_TOKEN_ENV = "samagotchi.traded_token"
 
       def fragment_trade?(req) = req.post? && req.path_info == TOKEN_TRADE_PATH
@@ -566,7 +592,7 @@ module Samagotchi
       # no longer works is cleared too, so the browser it was left in (the
       # owner's, who opened a participant link) is the owner's again.
       def refused_token(req)
-        response = grant_ended_response(req) || unauthorized(req)
+        response = grant_bound_response(req) || grant_ended_response(req) || unauthorized(req)
         return response if token_required?(req) || !Grants.token?(req.cookies[token_cookie_name(req)])
 
         status, headers, body = response
@@ -837,18 +863,27 @@ module Samagotchi
       # workers it starts run that one, not this chi web's version;
       # 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; public_url: web.public_url's origin, nil
-      # without one. A participant gets app, version and features only
+      # attached TUI needs (ATTACH_FEATURE); bound_grants: an invite takes an
+      # identity (BOUND_FEATURE). lan: its LAN address, nil when it listens
+      # on loopback only; proxy: {identity_header} behind an auth proxy
+      # (web.public_url or a tunnel; the header nil when none is trusted),
+      # nil without one: the Invite dialog's email field and chi share's
+      # warning. 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: INFO_FEATURES, lan: @lan && @lan[:ip] })
+                             cwd: Dir.pwd, start_dir: start_dir, features: INFO_FEATURES, lan: @lan && @lan[:ip],
+                             proxy: @public_url && { identity_header: @public_url.identity_header } })
       end
 
-      INFO_FEATURES = ["dir", "newest_workers", SessionAccessRoutes::FEATURE, SessionAccessRoutes::ATTACH_FEATURE].freeze
+      # POST …/participants takes an identity (a grant bound to it): a chi
+      # web without it would ignore one and issue an unbound grant, so chi
+      # --remote share --identity asks for this first.
+      BOUND_FEATURE = "bound_grants"
+      INFO_FEATURES = ["dir", "newest_workers", SessionAccessRoutes::FEATURE, SessionAccessRoutes::ATTACH_FEATURE,
+                       BOUND_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
@@ -1049,6 +1084,10 @@ module Samagotchi
         return not_live(id) unless client
 
         reply = request.call(client)
+        # Not the route's own 403 (a parent's option refused): the worker
+        # asked for a secret this chi web didn't send.
+        return error_response(502, BridgeSecret::ERROR, BridgeSecret::REFUSED) if reply.secret_refused?
+
         mapped = yield(reply)
         return mapped if mapped
 
@@ -1095,8 +1134,8 @@ module Samagotchi
       # The session's Bridge, waiting briefly for one a resume just spawned.
       # @return [BridgeClient, nil]
       def live_bridge_client(id)
-        port = bridge_sidecar_port(id) || await_bridge_port(id, timeout: [@bridge_wait_timeout.to_f, 5.0].min)
-        port && BridgeClient.new(session_id: id, port: port, host: DEFAULT_HOST)
+        sidecar = bridge_sidecar(id) || await_bridge_sidecar(id, timeout: [@bridge_wait_timeout.to_f, 5.0].min)
+        bridge_client_for(id, sidecar)
       end
 
       # The process holding the session (an OwnerLock::Owner), or nil. A worker always runs a Bridge; a TUI (plain `chi`) doesn't share.
@@ -1319,14 +1358,16 @@ module Samagotchi
         # Single live transport: proxy to the session's Bridge. When no live
         # worker exists there is nothing to stream — history is available via
         # GET /api/sessions/:id/output.
-        bridge_port = bridge_sidecar_port(id)
+        sidecar = bridge_sidecar(id)
         # A resume just spawned the worker: its bridge may still be binding.
         # Wait briefly for it so the first SSE connect lands on a live bridge
         # instead of an instantly-closed empty 200 / 503 during startup.
-        if bridge_port.nil? && @bridge_wait_timeout.to_i.positive?
-          bridge_port = await_bridge_port(id, timeout: [@bridge_wait_timeout.to_f, 2.0].min)
+        if sidecar.nil? && @bridge_wait_timeout.to_i.positive?
+          sidecar = await_bridge_sidecar(id, timeout: [@bridge_wait_timeout.to_f, 2.0].min)
         end
-        return error_response(503, "not_live", "no live bridge for session #{id}") unless bridge_port
+        return error_response(503, "not_live", "no live bridge for session #{id}") unless sidecar
+
+        client = bridge_client_for(id, sidecar)
 
         headers = {
           "Content-Type" => "text/event-stream",
@@ -1341,19 +1382,19 @@ module Samagotchi
         # handler supports hijacking, stream frames straight to the socket
         # instead of returning an enumerable.
         if req.env["rack.hijack?"]
-          hijack = sse_hijack(id, req, bridge_port)
+          hijack = sse_hijack(id, req, client)
           return [200, headers.merge("rack.hijack" => hijack), []]
         end
 
-        [200, headers, proxy_stream_body(id, req, bridge_port)]
+        [200, headers, proxy_stream_body(id, req, client)]
       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)
+      def proxy_stream_body(id, req, client)
         query = participant_view?(req) ? participant_stream_query(req) : stream_query(req)
-        ProxyStreamBody.new(host: DEFAULT_HOST, port: port, session_id: id, query: query, headers: req.env,
+        ProxyStreamBody.new(client: client, query: query, headers: req.env,
                             server_running: stream_running(principal(req)), filter: stream_filter(req, id))
       end
 
@@ -1424,45 +1465,47 @@ module Samagotchi
       # frames directly to the client socket until it disconnects. The handler
       # (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)
+      def sse_hijack(id, req, client)
         # 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)
+        body = proxy_stream_body(id, req, client)
         lambda do |io|
           body.each { |chunk| io.write(chunk) }
         rescue Errno::EPIPE, Errno::ECONNRESET, IOError
           nil # client went away — end the stream quietly
         rescue StandardError => e
-          Log.warn(:web, "proxy_failed", sid: id, port: port, error: e.class.name, msg: e.message)
+          Log.warn(:web, "proxy_failed", sid: id, port: client.port, error: e.class.name, msg: e.message)
           nil
         end
       end
 
       # Bounded wait for a freshly-spawned worker's bridge sidecar so the
       # response hands the client a live transport without client-side polling.
-      # Returns the bridge port, or nil when it is not up by the deadline (the
+      # Returns the bridge's sidecar (WorkerSidecar), or nil when it is not up by the deadline (the
       # session still exists; EventSource auto-reconnect covers late binders).
-      def await_bridge_port(session_id, timeout: @bridge_wait_timeout)
+      def await_bridge_sidecar(session_id, timeout: @bridge_wait_timeout)
         return nil if timeout.nil? || timeout <= 0
 
-        BridgeClient.poll(timeout, interval: BridgeClient::SPAWN_POLL_INTERVAL) { bridge_sidecar_port(session_id) }
+        BridgeClient.poll(timeout, interval: BridgeClient::SPAWN_POLL_INTERVAL) { bridge_sidecar(session_id) }
       rescue StandardError
         nil
       end
 
-      # Port of the session's live Bridge (stale sidecars are removed), or nil.
-      def bridge_sidecar_port(session_id)
+      # The session's live Bridge's sidecar (stale ones are removed), or nil:
+      # read again for every request, so a respawned worker's port and secret
+      # are the ones used.
+      # @return [WorkerSidecar, nil]
+      def bridge_sidecar(session_id)
         dir = @session_class.session_dir(session_id, state_dir: default_state_dir)
-        BridgeClient.sidecar_port(dir, host: DEFAULT_HOST)
+        BridgeClient.live_sidecar(dir, host: DEFAULT_HOST)
       rescue StandardError
         nil
       end
 
       # @return [BridgeClient, nil] a client for the session's live Bridge
-      def bridge_client(session_id)
-        port = bridge_sidecar_port(session_id)
-        port && BridgeClient.new(session_id: session_id, port: port, host: DEFAULT_HOST)
-      end
+      def bridge_client(session_id) = bridge_client_for(session_id, bridge_sidecar(session_id))
+
+      def bridge_client_for(session_id, sidecar) = BridgeClient.for_sidecar(session_id, sidecar, host: DEFAULT_HOST)
 
       # GET a read path of the session's live Bridge (+path+: "state",
       # "snapshot", "stats", ...).
@@ -1582,6 +1625,9 @@ module Samagotchi
         @state_dir || Session.default_state_dir
       end
 
+      # The folder chi web starts in (StartDir), the cwd when none was given.
+      def start_dir = @start_dir || Dir.pwd
+
       # The sessions folder as the page shows it: ~ for the home folder.
       def sessions_dir_label
         home_label(File.expand_path(default_state_dir))
@@ -1590,34 +1636,61 @@ module Samagotchi
       def home_label(dir) = Paths.tilde(dir)
 
       # <body> data for the page: where sessions are stored, where an
-      # all-view new chat starts (the server's cwd), and, when ?dir names a
+      # all-view new chat starts (the start folder), and, when ?dir names a
       # folder in a repo, that project's name and root. A bad dir adds
       # nothing here: the list call answers 400 and the page says so.
+      # Without ?dir (and without ?scope=all) the page is the start folder's
+      # project view when that folder is in a repo: data-scope-dir names it
+      # for the page (the URL stays bare, so a token's 303, a link code's
+      # #code= and the app's start_url "/" all land there). ?dir= beats
+      # ?scope=all.
       def index_data_attributes(req)
         # version: the chi that served the page; the events snapshot names
         # the one serving now (an upgraded chi web after a reconnect).
-        attrs = { "sessions-dir" => sessions_dir_label, "server-dir" => home_label(Dir.pwd), "version" => Samagotchi::VERSION }
+        attrs = { "sessions-dir" => sessions_dir_label, "server-dir" => home_label(start_dir), "version" => Samagotchi::VERSION }
         attrs["view"] = view_name(req.params["view"])
         # Only when on: the page reads its presence (the turn view ignores it).
         attrs["working-set"] = "1" if working_set?(req.params["working_set"])
-        # Always there: an empty one means no presets, not the default.
-        attrs["annotate-presets"] = @annotate_presets
+        attrs.merge!(annotate_presets_data)
         dir, = scope_dir(req.params["dir"])
+        unless dir
+          dir = default_scope_dir(req)
+          attrs["scope-dir"] = dir if dir
+        end
         root = dir && ProjectScope.root_for(dir)
         if root
           attrs["project-name"] = File.basename(root)
           attrs["project-dir"] = home_label(root)
         elsif dir.nil?
           # The all view's way back: the project view it came from
-          # (?from=), else the project chi web runs in.
+          # (?from=), else the project chi web starts in.
           back, = scope_dir(req.params["from"])
-          back ||= Dir.pwd
+          back ||= start_dir
           if (back_root = ProjectScope.root_for(back))
             attrs["back-name"] = File.basename(back_root)
             attrs["back-dir"] = back
           end
         end
-        attrs.map { |key, value| %(data-#{key}="#{Rack::Utils.escape_html(value)}") }.join(" ")
+        body_data(attrs)
+      end
+
+      # +attrs+ as <body> data attributes, each value escaped.
+      def body_data(attrs) = attrs.map { |key, value| %(data-#{key}="#{Rack::Utils.escape_html(value)}") }.join(" ")
+
+      # The Annotate presets (web.annotate_presets) for a page's <body>, the
+      # owner's and the participant page's. Always there: an empty one means
+      # no presets, not the default.
+      def annotate_presets_data = { "annotate-presets" => @annotate_presets }
+
+      # The folder a bare page (no ?dir, no ?scope=all) is scoped to: the
+      # start folder when it is still a folder in a repo, else nil (every
+      # session).
+      def default_scope_dir(req)
+        return nil unless req.params["dir"].to_s.strip.empty?
+        return nil if req.params["scope"] == "all"
+
+        dir = File.expand_path(start_dir)
+        File.directory?(dir) && ProjectScope.root_for(dir) ? dir : nil
       end
 
       VIEWS = Config::BY_KEY["web.view"].enum_values
@@ -1750,8 +1823,9 @@ module Samagotchi
         #   is kept (the env carries the token cookie, never held or inspected)
         # @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)
+        # @param client [BridgeClient] the session's Bridge (App#bridge_client_for)
+        def initialize(client:, query:, headers:, server_running: -> { true }, filter: nil)
+          @client = client
           @query = query
           @last_event_id = headers["HTTP_LAST_EVENT_ID"]
           @server_running = server_running

data/lib/samagotchi/web/grants.rb

@@ -14,6 +14,7 @@ require_relative "../participant_name"
 require_relative "../session"
 require_relative "../redacted_inspect"
 require_relative "private_files"
+require_relative "participant_exposure"
 
 module Samagotchi
   module Web
@@ -74,16 +75,54 @@ module Samagotchi
       # session".
       class Invalid < StandardError; end
 
+      # An identity to bind a grant to that isn't one email address.
+      class BadIdentity < Invalid
+        def initialize(msg = "a link is bound to one email address (name@domain: one @, no spaces or commas, ASCII " \
+                             "only)") = super
+      end
+
+      # An identity asked of a chi web that can't check one: no auth proxy
+      # naming the signed-in user (ProxyGate), so the link would never open.
+      class Unbindable < Invalid
+        def initialize(msg = "a link can be bound to an email only on a chi web behind an auth proxy that names the " \
+                             "signed-in user (web.public_url with web.proxy.identity_header, or chi web --tunnel " \
+                             "tailscale): bound here it would never open") = super
+      end
+
+      # The store's version: 1, and BOUND_VERSION once a grant is bound to
+      # an identity, so a chi that knows only 1 and checks (from this one
+      # on) doesn't rewrite it. MAX_VERSION is the newest this chi reads
+      # and writes; a newer store it reads but never writes (Newer).
+      VERSION = 1
+      BOUND_VERSION = 2
+      MAX_VERSION = 2
+
+      # A store chi won't write over (Corrupt, Newer): the owner's invite,
+      # cap and revoke are refused with its message.
+      class Unwritable < StandardError; end
+
       # The store is there but doesn't read (not JSON, a grant without its
       # digest or expiry): its grants find nothing (fail closed), and
       # nothing writes over it, which would lose every other grant.
-      class Corrupt < StandardError
+      class Corrupt < Unwritable
         def initialize(path, reason)
           super("#{path} can't be read (#{reason}): chi won't write over it; fix it, or move it aside to end " \
                 "every participant's link")
         end
       end
 
+      # The store was written by a newer chi (its version above
+      # MAX_VERSION): its grants still work here (read as this chi knows
+      # them), but nothing writes over it, which would drop what that chi
+      # added to them.
+      class Newer < Unwritable
+        def initialize(path, version)
+          super("#{path} was written by a newer chi (grants store version #{version}; this chi knows up to " \
+                "#{MAX_VERSION}): chi won't write over it, which would drop what that chi added; update chi " \
+                "(chi update)")
+        end
+      end
+
       # One participant's access to one session. +id+ (p_<8 hex>) names the
       # participant too: a turn they send is authored "p:<id>" (P3).
       # +revoked_by+ why it was revoked: "owner", "archive", "delete",
@@ -91,14 +130,26 @@ module Samagotchi
       # +cap+ (dollars) and +queue+ (turns waiting) as issued; nil in a
       # grant from before them, which takes the config's (#spend_cap,
       # #queue_limit).
+      # +exposure+: what the participant learns of the review's usage
+      # (ParticipantExposure; "own" for every grant today, and for one from
+      # before it). Kept as stored: a level this chi doesn't know reads as
+      # the narrowest, and is written back as it was.
+      # +extra+: the stored keys this chi doesn't know (a newer chi's,
+      # such as a field added to a grant without a version bump), written
+      # back as they were, so a rewrite here never drops them.
       Grant = Data.define(:id, :session_id, :digest, :kind, :name, :role, :created_at, :expires_at, :revoked_at,
-                          :revoked_by, :last_used_at, :cap, :queue, :identity) do
+                          :revoked_by, :last_used_at, :cap, :queue, :identity, :exposure, :extra) do
         # identity: the proxy identity (an email, lower case) the grant is
         # bound to, nil for any (ProxyGate; issued from shared-sessions P6).
-        def initialize(cap: nil, queue: nil, identity: nil, **) = super
+        def initialize(cap: nil, queue: nil, identity: nil, exposure: nil, extra: {}, **)
+          super(cap: cap, queue: queue, identity: identity, extra: extra,
+                exposure: exposure.nil? ? ParticipantExposure::DEFAULT : exposure, **)
+        end
 
         def self.from_h(hash)
-          new(**members.to_h { |key| [key, hash[key.to_s]] })
+          known = members - [:extra]
+          extra = hash.reject { |key, _| known.include?(key.to_s.to_sym) }
+          new(**known.to_h { |key| [key, hash[key.to_s]] }, extra: extra)
         end
 
         # The dollars this participant may cost the owner.
@@ -132,11 +183,24 @@ module Samagotchi
         def public_h(now)
           { id: id, session_id: session_id, kind: kind, name: name, role: role, created_at: created_at,
             expires_at: expires_at, revoked_at: revoked_at, revoked_by: revoked_by, last_used_at: last_used_at,
-            state: state(now).to_s, cap: spend_cap, queue: queue_limit }
+            state: state(now).to_s, cap: spend_cap, queue: queue_limit, identity: identity }
         end
 
-        # A grant bound to no identity is stored as before identity existed.
-        def to_store = to_h.transform_keys(&:to_s).tap { |hash| hash.delete("identity") if identity.nil? }
+        # A grant bound to no identity, with the default exposure, is stored
+        # as before either existed; the keys this chi doesn't know come
+        # after, as they were.
+        #
+        # A non-default exposure needs no version bump (identity's
+        # BOUND_VERSION): a chi that ignores it shows the participant the
+        # narrowest level, so it fails closed, and one that knows Grant#extra
+        # keeps it on a rewrite. A bump would only make that chi refuse the
+        # owner's invite, cap and revoke (Newer) for no safety gain.
+        def to_store
+          hash = to_h.except(:extra).transform_keys(&:to_s)
+          hash.delete("identity") if identity.nil?
+          hash.delete("exposure") if exposure == ParticipantExposure::DEFAULT
+          hash.merge(extra.reject { |key, _| hash.key?(key) })
+        end
 
         def inspect = "#<Grant #{id} #{session_id[0, 8]} #{name.inspect}>"
         alias_method :to_s, :inspect
@@ -191,6 +255,26 @@ module Samagotchi
 
       def self.token?(value) = value.is_a?(String) && value.start_with?(PREFIX)
 
+      # What a proxy identity header carries: an email, or a login such as
+      # Tailscale's alex@github (one @, a domain without a dot).
+      IDENTITY_RE = /\A[^@,<>"\\]+@[^@,<>"\\]+\z/
+      # No space or control character anywhere (a header can't carry one,
+      # and a name with one could mislead in a listing).
+      IDENTITY_BAD_RE = /\p{Space}|\p{Cc}/
+      IDENTITY_MAX = 254
+
+      # +identity+ as the gate compares it (ProxyGate#proxy_identity: strip,
+      # lower case).
+      # @raise [BadIdentity] not one email address
+      def self.clean_identity(identity)
+        # ASCII only, as ProxyGate#proxy_identity: its lower case is the same
+        # whatever the string's encoding.
+        clean = identity.is_a?(String) && identity.ascii_only? ? identity.strip.downcase : ""
+        raise BadIdentity unless clean.length <= IDENTITY_MAX && IDENTITY_RE.match?(clean) && !IDENTITY_BAD_RE.match?(clean)
+
+        clean
+      end
+
       # One line, at most NAME_MAX characters, no brackets (a name can't
       # forge the "[Review contribution from …]" header; ParticipantName).
       # @raise [Invalid] nothing left
@@ -226,10 +310,12 @@ module Samagotchi
       # A new grant for +session_id+, written before the token is handed out.
       # @param ttl [Integer, nil] seconds (nil: Grants.default_ttl; at most MAX_TTL)
       # @param cap [Numeric, nil] dollars (nil: Grants.default_cap)
+      # @param identity [String, nil] the proxy identity (an email) the grant
+      #   is bound to (Grants.clean_identity), nil for any
       # @param on_write [#call, nil] see #update
       # @return [Issued]
       # @raise [Invalid]
-      def issue(session_id:, name:, kind: "human", role: "reviewer", ttl: nil, cap: nil, on_write: nil)
+      def issue(session_id:, name:, kind: "human", role: "reviewer", ttl: nil, cap: nil, identity: nil, on_write: nil)
         Session.check_id!(session_id)
         ttl ||= Grants.default_ttl
         cap = Grants.default_cap if cap.nil?
@@ -239,13 +325,15 @@ module Samagotchi
         raise Invalid, CAP_RANGE unless Grants.cap?(cap)
 
         clean = Grants.clean_name(name)
+        identity = Grants.clean_identity(identity) unless identity.nil?
         token = "#{PREFIX}#{SecureRandom.urlsafe_base64(BYTES)}"
         issued = now
         update(on_write) do |grants|
           id = fresh_id(grants)
           grant = Grant.new(id: id, session_id: session_id, digest: Grants.digest(token), kind: kind, name: clean,
                             role: role, created_at: stamp(issued), expires_at: stamp(issued + ttl), revoked_at: nil,
-                            revoked_by: nil, last_used_at: nil, cap: cap.to_f, queue: Grants.default_queue)
+                            revoked_by: nil, last_used_at: nil, cap: cap.to_f, queue: Grants.default_queue,
+                            identity: identity)
           [grants + [grant], Issued.new(grant: grant, token: token)]
         end
       end
@@ -335,7 +423,7 @@ module Samagotchi
         update do |grants|
           [grants.map { |grant| grant.id == id ? grant.with(last_used_at: stamp(at)) : grant }, nil]
         end
-      rescue Corrupt
+      rescue Unwritable
         nil
       end
 
@@ -368,8 +456,13 @@ module Samagotchi
         grants
       end
 
+      # In a newer chi's store (Newer) a grant with fields this chi doesn't
+      # know is left out: such a field may restrict it (a binding moved to a
+      # new key), so it fails closed here. Its link works on that chi again.
       def reload(stamp)
-        @grants = stamp ? read : []
+        grants, version = stamp ? read : [[], VERSION]
+        grants = grants.select { |grant| grant.extra.empty? } if version > MAX_VERSION
+        @grants = grants
         @corrupt = nil
       rescue Corrupt => e
         @grants = []
@@ -377,19 +470,23 @@ module Samagotchi
         Log.warn(:web, "grants_unreadable", echo: "[chi web] #{e.message}", path: @path)
       end
 
+      # [grants, the store's version] (none yet: [[], VERSION]).
       # @raise [Corrupt] the file is there but isn't a grants store
       def read
         data = begin
           JSON.parse(File.read(@path))
         rescue Errno::ENOENT
-          return []
+          return [[], VERSION]
         rescue JSON::ParserError
           raise Corrupt.new(@path, "not JSON")
         end
         rows = data.is_a?(Hash) ? data["grants"] : nil
         raise Corrupt.new(@path, "no grants list") unless rows.is_a?(Array)
 
-        rows.each_with_index.map { |hash, index| grant_from(hash, index) }
+        version = data.fetch("version", VERSION)
+        raise Corrupt.new(@path, "a bad version") unless version.is_a?(Integer) && version >= VERSION
+
+        [rows.each_with_index.map { |hash, index| grant_from(hash, index) }, version]
       end
 
       # A stored grant the gate can compare and date, else Corrupt.
@@ -401,12 +498,21 @@ module Samagotchi
                   elsif !grant.digest.is_a?(String) || grant.digest.empty? then "no digest"
                   elsif !time?(grant.expires_at) then "no expiry"
                   elsif !grant.revoked_at.nil? && !time?(grant.revoked_at) then "a bad revoked_at"
+                  elsif !identity?(grant.identity) then "a bad identity"
                   end
         raise Corrupt.new(@path, "grant #{index + 1} has #{problem}") if problem
 
         grant
       end
 
+      # nil (unbound), or an identity as #issue stores it: anything else
+      # (false, "", a list) could read as unbound.
+      def identity?(value)
+        value.nil? || (value.is_a?(String) && Grants.clean_identity(value) == value)
+      rescue BadIdentity
+        false
+      end
+
       def time?(value)
         value.is_a?(String) && Time.iso8601(value)
       rescue ArgumentError
@@ -427,11 +533,16 @@ module Samagotchi
         File.open(File.join(dir, LOCK), File::RDWR | File::CREAT, 0o600) do |lock|
           lock.flock(File::LOCK_EX)
           # Never over a store that didn't read (Corrupt): the next write
-          # would keep only this one's change.
-          grants, result = yield(read)
+          # would keep only this one's change. Nor over a newer chi's
+          # (Newer): this chi would drop what it doesn't know.
+          stored, version = read
+          raise Newer.new(@path, version) if version > MAX_VERSION
+
+          grants, result = yield(stored)
           at = now
           kept = grants.reject { |grant| (ended = grant.ended_at(at)) && at - ended > KEEP_ENDED }
-          body = JSON.pretty_generate({ "version" => 1, "grants" => kept.map(&:to_store) })
+          version = [version, kept.any?(&:identity) ? BOUND_VERSION : VERSION].max
+          body = JSON.pretty_generate({ "version" => version, "grants" => kept.map(&:to_store) })
           AtomicFile.write(@path, "#{body}\n", perm: 0o600)
           @mutex.synchronize { @stamp = nil }
           on_write&.call(kept, result)

data/lib/samagotchi/web/link_codes.rb

@@ -56,25 +56,38 @@ module Samagotchi
       end
 
       # The code's [kind, token] (token nil for the owner's), once: the code
-      # is gone after. nil for an unknown, used or expired code.
+      # is gone after. nil for an unknown, used or expired code. With a
+      # block, it is asked (kind, token) first, under the lock: false keeps
+      # the code for another try and gives nil (a bound grant's code opened
+      # by another identity: decision C).
       def redeem(code)
         return nil unless LinkCodes.code?(code)
 
         wanted = digest(code)
-        found = nil
+        result = nil
         update do |entries|
-          entries.reject do |entry|
-            next false unless same_digest?(entry["digest"].to_s, wanted)
+          entry = entries.find { |candidate| same_digest?(candidate["digest"].to_s, wanted) }
+          next entries unless entry
 
-            found = entry
-            true
-          end
+          opened = open_entry(code, entry)
+          next entries if opened && block_given? && !yield(*opened)
+
+          result = opened
+          entries.reject { |candidate| candidate.equal?(entry) }
         end
-        return nil unless found
-        return nil if Time.iso8601(found["expires_at"]) <= @clock.call
+        result
+      end
+
+      private
+
+      def digest(code) = Digest::SHA256.hexdigest(code)
 
-        kind = found["kind"] == "grant" ? :grant : :owner
-        token = found["sealed"] && unseal(code, found["sealed"])
+      # [kind, token] for a live entry whose token unseals, else nil.
+      def open_entry(code, entry)
+        return nil if Time.iso8601(entry["expires_at"].to_s) <= @clock.call
+
+        kind = entry["kind"] == "grant" ? :grant : :owner
+        token = entry["sealed"] && unseal(code, entry["sealed"])
         return nil if kind == :grant && token.nil?
 
         [kind, token]
@@ -82,10 +95,6 @@ module Samagotchi
         nil
       end
 
-      private
-
-      def digest(code) = Digest::SHA256.hexdigest(code)
-
       def same_digest?(left, right) = left.bytesize == right.bytesize && OpenSSL.fixed_length_secure_compare(left, right)
 
       def key(code) = OpenSSL::KDF.hkdf(code, salt: "chi-link-code", info: "seal", length: 32, hash: "SHA256")