agents_control 0.2.3 → 0.3.0

data/lib/agents_control/doctor.rb

@@ -27,7 +27,7 @@ module AgentsControl
 
     CHECKS = %i[
       ruby_check terminal_check automation_check agent_binary_check
-      token_check chats_check bot_check daemon_check hooks_check
+      token_check chats_check passphrase_check bot_check daemon_check hooks_check
       anchors_check wake_check
     ].freeze
 
@@ -46,6 +46,24 @@ module AgentsControl
 
     private
 
+    # An unusable record is the case worth naming out loud: everywhere
+    # else it's treated as "no passphrase" so the command stays
+    # reachable, and without this nobody would ever learn that what
+    # they set isn't being used.
+    def passphrase_check
+      store = Passphrase.new(secrets: @secrets)
+
+      if store.unusable?
+        warn("passphrase", "stored, but not in a format this version reads",
+             "agents_control passphrase set — writes a fresh one")
+      elsif store.configured?
+        ok("passphrase", "set — destructive commands ask for it")
+      else
+        warn("passphrase", "not set — destructive commands ask for a tap",
+             "agents_control passphrase set")
+      end
+    end
+
     def ok(name, detail) = Check.new(name: name, status: :ok, detail: detail)
     def warn(name, detail, fix = nil) = Check.new(name: name, status: :warn, detail: detail, fix: fix)
     def fail(name, detail, fix = nil) = Check.new(name: name, status: :fail, detail: detail, fix: fix)

data/lib/agents_control/inbox.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module AgentsControl
+  # Files arriving from Telegram — a screenshot, a log, a CSV, a screen
+  # recording — landed on disk so an agent can read them.
+  #
+  # On disk, and not as a link, for one reason: Telegram serves file
+  # bytes from `/file/bot<TOKEN>/<path>`, so the download URL *is* the
+  # bot token. Handing that to an agent would put the token in its
+  # context, in the pane, and in the shell history — and this project
+  # treats a leaked bot token as equivalent to remote code execution.
+  # The URL is built inside Api#download and never leaves it. What the
+  # agent gets is a local path.
+  class Inbox
+    # Order matters: a photo comes as an array of sizes and the last is
+    # the largest, while a document carries the original filename. A
+    # message can hold exactly one of these.
+    KINDS = %w[document photo video audio voice video_note animation].freeze
+
+    # getFile refuses to serve anything larger, so a bigger file is
+    # rejected before the round trip rather than after it. The declared
+    # size is only the sender's word, though, so the same bound is
+    # enforced again on the bytes as they actually arrive.
+    MAX_BYTES = 20 * 1024 * 1024
+
+    # Kept out of the project directory on purpose: files arrive from a
+    # phone, and dropping them into whatever repository happened to be
+    # open would put them in front of `git status` and eventually into
+    # a commit.
+    def self.path
+      base = ENV["XDG_STATE_HOME"] || File.expand_path("~/.local/state")
+      File.join(base, "agents_control", "inbox")
+    end
+
+    Attachment = Struct.new(:file_id, :file_name, :file_size, :kind, keyword_init: true)
+
+    # The attachment in a message, or nil if it carries none.
+    def self.attachment(message)
+      KINDS.each do |kind|
+        value = message[kind]
+        next unless value
+
+        # photo is an array of increasing sizes; the last is the one
+        # worth having, since the smaller ones are Telegram's own
+        # thumbnails rather than what was sent.
+        descriptor = value.is_a?(Array) ? value.last : value
+        next unless descriptor.is_a?(Hash) && descriptor["file_id"]
+
+        return Attachment.new(file_id: descriptor["file_id"], file_name: descriptor["file_name"],
+                              file_size: descriptor["file_size"], kind: kind)
+      end
+
+      nil
+    end
+
+    class TooLarge < StandardError; end
+
+    def initialize(api:, dir: self.class.path, keep_days: 14)
+      @api = api
+      @dir = dir
+      @keep_days = keep_days
+    end
+
+    # The local path the file landed at.
+    def fetch(attachment)
+      size = attachment.file_size.to_i
+      raise TooLarge, "#{human(size)} is over the #{human(MAX_BYTES)} Telegram allows a bot to download" if size > MAX_BYTES
+
+      remote = @api.file_path_for(attachment.file_id)
+      prepare
+      destination = File.join(@dir, name_for(attachment, remote))
+
+      download(remote, destination)
+      prune
+      destination
+    end
+
+    private
+
+    # Downloaded beside the destination and renamed into place: a
+    # connection that drops half way through otherwise leaves a
+    # truncated file with a name that promises a whole one, and the
+    # agent reads it as though it were complete.
+    def download(remote, destination)
+      partial = "#{destination}.part"
+      @api.download(remote, to: partial, max_bytes: MAX_BYTES)
+      File.chmod(0o600, partial)
+      File.rename(partial, destination)
+    ensure
+      FileUtils.rm_f(partial) if partial && File.exist?(partial)
+    end
+
+    def prepare
+      FileUtils.mkdir_p(@dir)
+      # Logs and screenshots are exactly the kind of thing that carries
+      # a token or a customer's name through in passing.
+      File.chmod(0o700, @dir)
+    end
+
+    # A timestamp prefix rather than a check for collisions: two
+    # screenshots sent a minute apart are both called Screenshot.png,
+    # and the second one silently replacing the first is worse than
+    # having both.
+    def name_for(attachment, remote)
+      stamp = Time.now.strftime("%Y%m%d-%H%M%S")
+      base = sanitize(attachment.file_name)
+      # The fallback extension comes from getFile's answer, which is
+      # Telegram's word and not ours — the API client escapes the same
+      # value per segment before it goes into a URL, and it gets the
+      # same treatment here rather than being spliced into a filename
+      # that will be typed into a shell.
+      base = "#{attachment.kind}#{extension(remote)}" if base.empty?
+
+      "#{stamp}-#{base}"
+    end
+
+    # Its own cleaning rather than sanitize's, which is written for a
+    # whole filename and strips the leading dot an extension needs.
+    # Everything but word characters and dots goes: this ends up in a
+    # path that gets typed into a shell, and it comes from getFile's
+    # answer — Telegram's word, not ours. The API client escapes the
+    # same value per segment before putting it in a URL.
+    def extension(remote)
+      File.extname(remote.to_s).gsub(/[^\w.]/, "")[0, 16]
+    end
+
+    # The name comes from whoever sent the file. It decides a path here,
+    # so it doesn't get to contain one: no separators, no traversal, no
+    # leading dot to hide the result, and short enough for any
+    # filesystem to accept.
+    def sanitize(name)
+      # Stripped before File.basename, which raises on a null byte
+      # rather than returning anything — and the name is JSON from
+      # Telegram, so it can carry one.
+      safe = name.to_s.delete("\u0000").tr("\n\r\t", " ")
+      cleaned = File.basename(safe).gsub(/[^\w.\- ]/, "_").squeeze("_").strip
+      cleaned = cleaned.sub(/\A\.+/, "")
+
+      cleaned.length > 96 ? "#{cleaned[0, 60]}#{File.extname(cleaned)[0, 16]}" : cleaned
+    end
+
+    # Nothing here is meant to be kept: an agent reads the file within
+    # minutes of it arriving. Without this the directory only ever
+    # grows, and it's full of screenshots and logs.
+    def prune
+      cutoff = Time.now - (@keep_days * 24 * 60 * 60)
+
+      Dir.glob(File.join(@dir, "*")).each do |path|
+        FileUtils.rm_f(path) if File.file?(path) && File.mtime(path) < cutoff
+      end
+    rescue SystemCallError
+      # A directory that can't be tidied is not a reason to refuse the
+      # file that was just asked for.
+      nil
+    end
+
+    def human(bytes) = "#{(bytes / 1024.0 / 1024.0).round(1)}MB"
+  end
+end

data/lib/agents_control/passphrase.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "securerandom"
+
+module AgentsControl
+  # The passphrase that unlocks a catastrophic command from Telegram.
+  #
+  # Stored the same place as the bot token — Keychain or libsecret,
+  # never the config file, never argv — and stored derived rather than
+  # plain: a token grants access, so it has to be readable back, but a
+  # passphrase only ever has to be *checked*, and there's no reason to
+  # keep something readable when a comparison would do.
+  #
+  # PBKDF2-HMAC-SHA256 through OpenSSL, which is stdlib. bcrypt or
+  # argon2 would be better at resisting an offline attack, and both are
+  # native extensions — the gem promises a pure-Ruby install with
+  # nothing to compile, and that promise is worth more here than the
+  # margin: anyone who can read this hash out of the Keychain can
+  # already read the bot token sitting next to it, which is the whole
+  # machine anyway.
+  class Passphrase
+    KEY = "run_passphrase"
+    ITERATIONS = 210_000
+    LENGTH = 32
+
+    # The wizard's two prompts are minutes apart at most, but what
+    # bridges them is written to the store on disk (0600, with a TTL) —
+    # so it gets the same cost as the record it will become. Cheaper
+    # here would mean the throwaway derivation is the easier of the two
+    # to attack offline, which is a strange place to save 200ms.
+    SEAL_ITERATIONS = ITERATIONS
+    PREFIX = "pbkdf2-sha256"
+
+    # A passphrase short enough to guess isn't protecting anything from
+    # someone holding an unlocked phone, which is the case this exists
+    # for in the first place.
+    MINIMUM = 8
+
+    class TooShort < StandardError; end
+
+    # The write went nowhere. Secrets#set reports which provider it
+    # picked, not whether that provider succeeded, and a Keychain that
+    # refused (locked, no authorization from a background daemon) would
+    # otherwise be indistinguishable from one that saved — leaving
+    # someone told their passphrase is set while destructive commands
+    # go on asking for a tap.
+    class NotSaved < StandardError; end
+
+    def initialize(secrets: Secrets.new)
+      @secrets = secrets
+    end
+
+    # "There's a record this version can actually check against", not
+    # "the entry isn't empty". The two diverge exactly when something
+    # unusable is stored — a plain string put in the environment
+    # variable, a truncated write, a format from a version this one was
+    # downgraded from — and every one of those would otherwise ask for
+    # a passphrase that can never match. Unusable is treated as absent,
+    # which falls back to the confirmation button rather than locking
+    # the command away. `doctor` reports the difference, so it isn't
+    # silent.
+    def configured? = !parse(stored).nil?
+
+    # Whether something is stored that isn't usable — for doctor, which
+    # is the one place that should say so out loud.
+    def unusable? = !stored.to_s.empty? && parse(stored).nil?
+
+    def set(plain)
+      value = plain.to_s
+      raise TooShort, "the passphrase needs at least #{MINIMUM} characters" if value.length < MINIMUM
+
+      salt = SecureRandom.hex(16)
+      @secrets.set(KEY, [PREFIX, ITERATIONS, salt, derive(value, salt, ITERATIONS)].join("$"))
+
+      raise NotSaved, "the secret store didn't keep it" unless matches?(value)
+
+      true
+    end
+
+    def clear = @secrets.delete(KEY)
+
+    # False whenever anything is off — no passphrase set, a record this
+    # version doesn't understand, an empty candidate. A check that
+    # can't be made is a check that didn't pass.
+    def matches?(candidate)
+      record = parse(stored)
+      return false unless record
+      return false if candidate.to_s.empty?
+
+      secure_compare(derive(candidate.to_s, record[:salt], record[:iterations]), record[:hash])
+    end
+
+    # Derives against a throwaway salt so two entries can be compared
+    # without either being kept. The wizard asks twice, and the first
+    # answer waits for the second in the store — as a derivation, never
+    # as the passphrase itself.
+    def self.sealed(value)
+      salt = SecureRandom.hex(16)
+      [salt, OpenSSL::KDF.pbkdf2_hmac(value.to_s, salt: salt, iterations: SEAL_ITERATIONS,
+                                                  length: LENGTH, hash: "SHA256").unpack1("H*")]
+    end
+
+    def self.sealed_matches?(sealed, candidate)
+      salt, expected = sealed
+      return false if salt.to_s.empty? || candidate.to_s.empty?
+
+      OpenSSL.secure_compare(
+        OpenSSL::KDF.pbkdf2_hmac(candidate.to_s, salt: salt, iterations: SEAL_ITERATIONS,
+                                                 length: LENGTH, hash: "SHA256").unpack1("H*"),
+        expected.to_s
+      )
+    end
+
+    private
+
+    # Read past the environment-variable provider on purpose. A
+    # passphrase is only ever checked, never read back, so there's no
+    # reason to accept one from the environment — and a plain one put
+    # in AGENTS_CONTROL_RUN_PASSPHRASE would take precedence over the
+    # Keychain, match nothing, and lock the command away for good:
+    # `passphrase clear` only writes to writable providers, and the
+    # environment isn't one.
+    def stored
+      @secrets.get(KEY, skip: Secrets::Providers::Env)
+    end
+
+    # A record is four fields with our prefix, a salt, a positive
+    # iteration count, and a hash. Anything else is not a passphrase
+    # this version can check.
+    def parse(record)
+      prefix, iterations, salt, hash = record.to_s.split("$", 4)
+      return unless prefix == PREFIX
+      return unless salt.to_s.length.positive? && hash.to_s.length.positive?
+      return unless iterations.to_s.match?(/\A[1-9][0-9]*\z/)
+
+      { iterations: iterations.to_i, salt: salt, hash: hash }
+    end
+
+    def derive(value, salt, iterations)
+      OpenSSL::KDF.pbkdf2_hmac(value, salt: salt.to_s, iterations: iterations,
+                                      length: LENGTH, hash: "SHA256").unpack1("H*")
+    end
+
+    # Fixed-time comparison. The attacker here is someone typing into a
+    # Telegram chat rather than measuring microseconds, so this is
+    # closer to hygiene than to a threat being answered — but a
+    # comparison that leaks its answer through timing is never the
+    # right one to write.
+    def secure_compare(one, two)
+      OpenSSL.secure_compare(one.to_s, two.to_s)
+    end
+  end
+end

data/lib/agents_control/policy.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module AgentsControl
+  # Recognises a command from Telegram that must not go into a pane
+  # blind — the handful that destroy a disk or the machine outright.
+  #
+  # This is a seatbelt, not a security system. It answers one question:
+  # did the phone in someone's pocket just send something there is no
+  # coming back from? A wrong tab number in a list, a command pasted
+  # into the wrong chat, a thumb on the wrong line — those are the
+  # cases, and they're the reason the list stays small enough to hold
+  # in your head.
+  #
+  # The outcome is never a refusal. The person on the other end owns
+  # the machine; a check they can't get past doesn't prevent anything,
+  # it just makes them walk to the laptop and type it there.
+  class Policy
+    Verdict = Struct.new(:action, :reason, keyword_init: true) do
+      def allow? = action == :allow
+      def confirm? = action == :confirm
+    end
+
+    ALLOWED = Verdict.new(action: :allow).freeze
+
+    # Targets that make a recursive force delete unrecoverable rather
+    # than merely annoying. `rm -rf /tmp/build` is someone's ordinary
+    # Tuesday; `rm -rf ~` is the end of the machine.
+    FATAL_TARGETS = ["/", "/*", "~", "~/", "~/*", "$HOME", "$HOME/*", "${HOME}", "${HOME}/*",
+                     "/usr", "/etc", "/var", "/System", "/Library", "/Applications",
+                     "/Users", "/home", "/opt", "/bin", "/sbin"].freeze
+
+    # The bar for an entry: catastrophic, irreversible, and nobody
+    # types it from a phone on purpose. Not "sensitive", not "usually a
+    # mistake" — `cat .env` and `git push --force` are somebody's
+    # ordinary afternoon, and a list that stops those trains people to
+    # tap past it without reading, which costs more than it saves.
+    #
+    # Each carries its own plain-language reason. "Matches a pattern"
+    # tells someone glancing at a phone nothing they can act on; "this
+    # erases your home directory" does.
+    CATASTROPHIC = [
+      [/:\(\)\s*\{[^}]*\|[^}]*&[^}]*\}\s*;\s*:/,
+       "that's a fork bomb — it locks the machine up until it's power-cycled"],
+      [/\bmkfs(\.\w+)?\b/,
+       "mkfs formats a filesystem — everything on that device is gone"],
+      [/\bdd\b[^|;]*\bof=\/dev\//,
+       "dd writing to a raw device destroys whatever filesystem is on it"]
+    ].freeze
+
+    # An `rm` carrying both a recursive and a force flag — bundled
+    # (-rf, -fr, -Rf) or apart (-r -f, --recursive --force) — aimed at
+    # something there's no coming back from. Matched on the parsed
+    # operands rather than as a substring: "rm -rf /" and
+    # "rm -rf /tmp/build" differ by one character as text, and by
+    # everything else in what they do.
+    def self.reckless_delete(command)
+      words = command.to_s.split
+      # Matched on the command's basename, and case-insensitively:
+      # `/bin/rm` is the same program, and macOS's case-insensitive
+      # filesystem happily runs `RM` as well.
+      at = words.index { |word| File.basename(word).casecmp?("rm") }
+      return unless at
+
+      flags, operands = words.drop(at + 1).partition { |word| word.start_with?("-") }
+      joined = flags.join(" ")
+      return unless joined.match?(/--recursive|-[a-zA-Z]*[rR]/) && joined.match?(/--force|-[a-zA-Z]*f/)
+
+      target = operands.find { |operand| fatal_target?(operand) }
+      "this recursively deletes #{target} — there is no undo" if target
+    end
+
+    # Quotes come off before comparing: `rm -rf "$HOME"` is an entirely
+    # ordinary way to type the thing this exists to catch, and it isn't
+    # the same string as `rm -rf $HOME`.
+    def self.fatal_target?(operand)
+      bare = operand.to_s.gsub(/\A['"]|['"]\z/, "")
+
+      FATAL_TARGETS.include?(bare) || FATAL_TARGETS.include?(bare.chomp("/"))
+    end
+
+    def self.catastrophic(command)
+      reckless = reckless_delete(command)
+      return reckless if reckless
+
+      CATASTROPHIC.find { |pattern, _| command.to_s.match?(pattern) }&.last
+    end
+
+    def self.check(command)
+      fatal = catastrophic(command)
+
+      fatal ? Verdict.new(action: :confirm, reason: fatal) : ALLOWED
+    end
+  end
+end

data/lib/agents_control/screen_watcher.rb

@@ -95,17 +95,28 @@ module AgentsControl
     # Looks for the last textual occurrence of "❯ 1. …" — the one
     # closest to the screen's current state, not a random numbered list
     # left over somewhere higher in the scrollback.
+    #
+    # Options don't have to be adjacent lines: a richer menu (a skill's
+    # own wizard, say) draws a couple of lines of description under
+    # each one, or a divider before a trailing meta-option ("Chat about
+    # this"). Anything that isn't itself the next numbered option is
+    # just skipped over rather than ending the scan — the option only
+    # actually ends once a numbered line shows up out of sequence
+    # (a stray list elsewhere on screen), which is what keeps this from
+    # picking up something unrelated further down.
     def parse_menu(text)
       lines = text.to_s.each_line.map(&:chomp)
       start = lines.rindex { |line| line.match?(CURSOR_OPTION) }
       return [] unless start
 
       options = [lines[start][CURSOR_OPTION, 1]]
-      index = start + 1
 
-      while index < lines.size && (m = lines[index].match(OPTION)) && m[1].to_i == options.size + 1
+      lines[(start + 1)..].to_a.each do |line|
+        m = line.match(OPTION)
+        next unless m
+        break unless m[1].to_i == options.size + 1
+
         options << m[2]
-        index += 1
       end
 
       options.size >= 2 ? options : []

data/lib/agents_control/secrets.rb

@@ -25,8 +25,12 @@ module AgentsControl
       @providers = providers || default_providers
     end
 
-    def get(key)
+    # skip names a provider class to read past — for a secret that has
+    # no business coming from one of them (see Passphrase).
+    def get(key, skip: nil)
       readable.each do |provider|
+        next if skip && provider.is_a?(skip)
+
         value = provider.get(key.to_s)
         return value if value && !value.empty?
       end

data/lib/agents_control/terminals/base.rb

@@ -61,8 +61,19 @@ module AgentsControl
       FIELD = "\x1F"
       RECORD = "\x1E"
 
+      # tmux 3.5 prints a non-printable byte in -F output as its octal
+      # escape — the four characters "\037" — where 3.7 emits the byte
+      # itself. Splitting on the byte then finds nothing, and the whole
+      # backend reports no panes at all: on Debian 13 and Ubuntu 24.10,
+      # whose tmux is 3.5a, the tool showed an empty tab list and gave
+      # no hint why. Both forms are accepted rather than betting on a
+      # version, and only these two sequences are converted — a window
+      # name containing the literal text is not something to go looking
+      # for.
+      ESCAPED = { "\\037" => FIELD, "\\036" => RECORD }.freeze
+
       def parse_records(output, fields)
-        output.split(RECORD).filter_map do |record|
+        output.to_s.gsub(/\\03[67]/, ESCAPED).split(RECORD).filter_map do |record|
           next if record.strip.empty?
 
           values = record.split(FIELD, -1)

data/lib/agents_control/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AgentsControl
-  VERSION = "0.2.3"
+  VERSION = "0.3.0"
 end

data/lib/agents_control.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "io/console"
+require "shellwords"
 
 # The base error is declared before the other files: error classes
 # inherit from it right in a class body (the Telegram client, for
@@ -29,6 +30,9 @@ require_relative "agents_control/transcript"
 require_relative "agents_control/agents/base"
 require_relative "agents_control/agents/claude_code"
 require_relative "agents_control/hooks/server"
+require_relative "agents_control/inbox"
+require_relative "agents_control/passphrase"
+require_relative "agents_control/policy"
 require_relative "agents_control/dispatcher"
 require_relative "agents_control/channels/base"
 require_relative "agents_control/channels/telegram/markdown"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: agents_control
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.3.0
 platform: ruby
 authors:
 - Sapar Kurmanov
@@ -58,9 +58,12 @@ files:
 - lib/agents_control/event.rb
 - lib/agents_control/executor.rb
 - lib/agents_control/hooks/server.rb
+- lib/agents_control/inbox.rb
 - lib/agents_control/keyboard.rb
 - lib/agents_control/menu.rb
+- lib/agents_control/passphrase.rb
 - lib/agents_control/pending.rb
+- lib/agents_control/policy.rb
 - lib/agents_control/process_probe.rb
 - lib/agents_control/prompt.rb
 - lib/agents_control/rate_limit_watcher.rb