ace-lab 0.13.0 → 0.14.0

data/lib/ace/lab/auth/lease_store.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "json"
+require "fileutils"
+require "digest"
+require "time"
+
+module Ace
+  module Lab
+    module Auth
+      # The ONE owner of the minimal lease record (task 8xs.t.pu0.7):
+      # one JSON file per lease under the trusted leases dir (default
+      # /var/lib/lab/ace-lab/auth/leases), private to the issuer. The
+      # record carries the correlation (task/assignment/profile/role/
+      # principal), the provider TOKEN REFERENCE (never the secret
+      # value), the deadlines and the cleanup outcome — never task
+      # progress, queues, or another tool's state.
+      #
+      # Lifecycle: a record is born PREPARING (issue in flight — a hard
+      # process death in that window leaves a recoverable record, never
+      # a phantom "live" grant); it becomes ISSUED only after a
+      # complete, usable credential handoff; an unresolved remote
+      # outcome (lost response, lost revoke) is REVOKE-PENDING until
+      # reconciled; REVOKED is terminal. Every write is atomic
+      # (temporary file + fsync + rename) under a STABLE sidecar write
+      # lock — a crash mid-write can never truncate or half-replace a
+      # record, and an unparseable record surfaces as a visible CORRUPT
+      # marker instead of silently vanishing from the inventory.
+      class LeaseStore
+        STATES = %w[preparing issued revoke-pending revoked].freeze
+
+        attr_reader :dir
+
+        def initialize(dir)
+          @dir = dir
+        end
+
+        # @param id [String, nil] caller-generated lease id (so the
+        #   provider's deterministic token_ref can be computed from it
+        #   and written in the SAME atomic creation write)
+        # @param token_ref [String, nil] the provider's DETERMINISTIC
+        #   remote identity for this lease, written at creation so an
+        #   interrupted issue can still be reconciled against the
+        #   remote side (the response may never have arrived).
+        # @return [Hash] the created (PREPARING) lease record
+        def create(profile:, role:, principal:, task:, assignment:, repos:,
+          use_until:, provider_expiry:, token_ref: nil, id: nil)
+          lease = {"id" => id || "lease-#{SecureRandom.hex(8)}",
+                   "profile" => profile, "role" => role, "principal" => principal,
+                   "task" => task, "assignment" => assignment, "repos" => repos.sort,
+                   "state" => "preparing", "requested_at" => now,
+                   "use_until" => use_until, "provider_expiry" => provider_expiry,
+                   "token_ref" => token_ref, "cleanup" => nil}
+          write(lease)
+          lease
+        end
+
+        # Idempotency: the LIVE lease for the same task/assignment/
+        # profile/role correlation, if any. Only an ISSUED record is
+        # live: preparing (issue in flight or dead mid-issue) and
+        # revoke-pending (unresolved remote outcome) records are never
+        # returned — recovery settles them instead. A finished or
+        # scope-changed correlation does not match, and
+        # DEADLINE-AWARENESS is part of the match: an issued record
+        # past its use_until/provider expiry is not returned, so a
+        # retry mints a fresh grant while reconcile retires the expired
+        # one — an expired grant is never handed back as "live".
+        def find_live(task:, assignment:, profile:, role:)
+          all.filter_map do |lease|
+            next unless lease["task"] == task && lease["assignment"] == assignment &&
+              lease["profile"] == profile && lease["role"] == role &&
+              lease["state"] == "issued"
+            lease if live?(lease)
+          end.min_by { |lease| lease["requested_at"].to_s }
+        end
+
+        def load(id)
+          path = lease_path(id)
+          raise Error, "unknown lease '#{id}'" unless File.file?(path)
+
+          JSON.parse(File.read(path))
+        rescue JSON::ParserError
+          raise Error, "lease record '#{id}' is unreadable"
+        end
+
+        # The full inventory, including CORRUPT records as explicit
+        # markers: a record that cannot be parsed is a visible recovery
+        # problem (the remote token may still be live) — never a
+        # silently skipped entry that disappears from reconcile.
+        def all
+          return [] unless Dir.exist?(@dir)
+
+          Dir.glob(File.join(@dir, "*.json")).sort.filter_map do |path|
+            JSON.parse(File.read(path))
+          rescue Errno::EACCES
+            nil
+          rescue JSON::ParserError
+            {"id" => File.basename(path, ".json"), "state" => nil,
+             "corrupt" => true, "_path" => path}
+          end
+        end
+
+        # Atomic update under a STABLE sidecar write lock: the record is
+        # read, modified and replaced via temporary-file + fsync +
+        # rename. A crash at any point leaves either the old or the new
+        # complete record — never a truncated file — and the lock
+        # survives the replacement (it is not held on the record inode).
+        def update(id)
+          path = lease_path(id)
+          with_write_lock(id) do
+            lease = begin
+              JSON.parse(File.read(path))
+            rescue JSON::ParserError, Errno::ENOENT => e
+              # A corrupt/missing record is a named store failure, never a
+              # raw parser error escaping through the update seam.
+              raise Error, "lease '#{id}' cannot be read at #{path}: #{e.class} #{e.message}"
+            end
+            yield(lease)
+            atomic_write(path, lease)
+            lease
+          end
+        end
+
+        def write(lease)
+          atomic_write(lease_path(lease["id"]), lease)
+          lease
+        end
+
+        def with_write_lock(id)
+          FileUtils.mkdir_p(@dir)
+          File.open(File.join(@dir, "#{id}.write.lock"), File::CREAT | File::RDWR) do |lock|
+            lock.flock(File::LOCK_EX)
+            yield
+          end
+        end
+
+        # One request flow at a time per correlation (task/assignment/
+        # profile/role): a BLOCKING exclusive lock on the correlation's
+        # lockfile so the find_live + create + issue sequence is atomic
+        # against a concurrent identical request — the second caller
+        # waits and then returns the first caller's live lease.
+        def with_correlation_lock(task:, assignment:, profile:, role:)
+          FileUtils.mkdir_p(@dir)
+          key = Digest::SHA256.hexdigest([task, assignment, profile, role].join("\e"))
+          File.open(File.join(@dir, "correlation-#{key}.lock"), File::CREAT | File::RDWR) do |lock|
+            lock.flock(File::LOCK_EX)
+            yield
+          end
+        end
+
+        # One exec at a time per lease: an exclusive lock on the lease's
+        # exec lockfile, non-blocking — a parallel exec is a refusal.
+        def with_exec_lock(id)
+          FileUtils.mkdir_p(@dir)
+          File.open(File.join(@dir, "#{id}.exec.lock"), File::CREAT | File::RDWR) do |lock|
+            unless lock.flock(File::LOCK_EX | File::LOCK_NB)
+              raise Error, "lease '#{id}' already has a running exec"
+            end
+
+            yield
+          end
+        end
+
+        # Usable NOW: only an ISSUED record inside its deadlines. A
+        # preparing record was never delivered (or the process died
+        # mid-issue) and a revoke-pending record has no valid handoff
+        # or is mid-revocation — neither is ever usable or "live".
+        def live?(lease, at: Time.now)
+          return false unless lease["state"] == "issued"
+          return false if lease["use_until"] && Time.parse(lease["use_until"]) <= at
+          if lease["provider_expiry"] && Time.parse(lease["provider_expiry"]) <= at
+            return false
+          end
+
+          true
+        end
+
+        private
+
+        def atomic_write(path, lease)
+          FileUtils.mkdir_p(@dir)
+          temporary = "#{path}.#{Process.pid}.tmp"
+          File.open(temporary, "w") do |file|
+            file.write(JSON.pretty_generate(lease))
+            file.flush
+            file.fsync
+          end
+          # 0600 BEFORE the rename: the record never exists at the target
+          # path with umask-default permissions, even for an instant.
+          FileUtils.chmod(0o600, temporary)
+          begin
+            File.rename(temporary, path)
+          rescue Errno::ENOENT
+            FileUtils.mkdir_p(File.dirname(path))
+            File.rename(temporary, path)
+          end
+        end
+
+        def lease_path(id)
+          raise Error, "invalid lease id" unless id.to_s.match?(/\Alease-[a-f0-9]{16}\z/)
+
+          File.join(@dir, "#{id}.json")
+        end
+
+        def now
+          Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ")
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/auth/plugins/env_provider.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Ace
+  module Lab
+    module Auth
+      module Plugins
+        # The env provider (task 8xs.t.pu0.7): exposes ONLY the named
+        # values of the configured safe sources to the leased child
+        # process. The host's whole environment and inherited
+        # credential overrides are never passed through; a standalone
+        # env profile declares process-scoped exposure only (the schema
+        # rejects it for profiles demanding remote expiry/revoke).
+        # When env is the HANDOFF of a provider lease, the same file
+        # carries that provider's token — this class is the standalone
+        # case.
+        class EnvProvider
+          def capabilities
+            {"expiry_mode" => "process"}
+          end
+
+          # @param issuer_env [Hash] the issuer process environment (the
+          #   trusted values the profile names)
+          def initialize(issuer_env: ENV.to_h)
+            @issuer_env = issuer_env
+          end
+
+          # Deterministic remote identity: the exposure is process-
+          # scoped, so the reference is fixed and revocation is local.
+          def token_ref_for(lease_id:)
+            "env:#{lease_id}"
+          end
+
+          def issue(profile:, lease:)
+            names = profile.fetch("env_names")
+            raise Providers::RefusedError,
+              "the env profile declares no env_names" if names.empty?
+
+            values = names.to_h do |name|
+              value = @issuer_env[name]
+              raise Providers::RefusedError,
+                "issuer environment does not provide '#{name}'" if value.nil? || value.empty?
+
+              [name, value]
+            end
+
+            {"token" => JSON.generate(values), "token_ref" => "env:#{lease["id"]}",
+             "provider_expiry" => nil,
+             "via" => {"kind" => "env", "names" => names.sort}}
+          end
+
+          def revoke(profile:, token_ref:, token: nil)
+            # Process-scoped exposure ends with the process; there is no
+            # remote state to revoke and never a claimed remote expiry.
+            :revoked
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/auth/plugins/forgejo_provider.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+require "open3"
+require "tempfile"
+
+module Ace
+  module Lab
+    module Auth
+      module Plugins
+        # Forgejo provider (task 8xs.t.pu0.7): one SEPARATE scoped token
+        # per lease, issued on the configured role account through the
+        # TOKEN-AUTHENTICATED ADMIN API, limited to the profile's
+        # repositories and scopes; revocation deletes that EXACT token
+        # name — never a prefix wipe and never other tasks' tokens.
+        #
+        # Wire contract (PR #398 re-review R1): the issuer credential is
+        # an admin PAT, so both endpoints are the admin variants
+        # (`POST/DELETE /api/v1/admin/users/{account}/tokens`) — the
+        # user-scoped `/api/v1/users/.../tokens` requires BasicAuth or
+        # reverse-proxy auth and does not accept `Authorization: token`.
+        # Repository scoping uses the server's RepoTargetOption shape:
+        # objects with `owner` and `name`. A repo entry without an
+        # owner does not identify anything and is REFUSED before any
+        # request — never an all-repositories token. The creation
+        # response's granted scopes are validated against the request
+        # when the server reports them; a mismatch is a classified
+        # failure, never a trusted grant. Forgejo tokens carry no proven
+        # native TTL across versions, so the profile's expiry comes
+        # from the host's scheduled revoke (expiry_mode host-revoke).
+        #
+        # The token NAME is deterministic from the lease id
+        # (`ace-lab-<lease id>`): it is written to the lease record at
+        # CREATION, so an interrupted issue (lost response, dead
+        # process) can still be settled deterministically — the name is
+        # reconstructed and revoked; a 404 means it never existed
+        # remotely (:already_invalid, an idempotent result).
+        #
+        # Transport is an injectable seam (argv runner/capture shapes):
+        # tests pin the wire contract with fakes emulating the server;
+        # the default runs `curl` with the issuer token from the host's
+        # protected store. The issuer secret is read from its file
+        # reference and never appears in argv of the CHILD.
+        class ForgejoProvider
+          def initialize(runner: nil, capture: nil)
+            @runner = runner || method(:run_curl)
+            @capture = capture || method(:run_capture)
+          end
+
+          def capabilities
+            {"expiry_mode" => "host-revoke"}
+          end
+
+          # Deterministic remote identity: the Forgejo token name is
+          # derived from the lease id alone — known before any response.
+          def token_ref_for(lease_id:)
+            "ace-lab-#{lease_id}"
+          end
+
+          def issue(profile:, lease:)
+            issuer = profile.fetch("issuer")
+            url = issuer["url"] or raise Providers::RefusedError, "forgejo profile has no issuer url"
+            account = issuer["account"] or raise Providers::RefusedError, "forgejo profile has no role account"
+            token_file = issuer["token_file"] or raise Providers::RefusedError,
+              "forgejo profile has no issuer token_file reference"
+            raise Providers::RefusedError, "issuer token file '#{token_file}' is not readable" unless File.readable?(token_file)
+
+            token_name = token_ref_for(lease_id: lease["id"])
+            scopes = profile.fetch("scopes")
+            repositories = repo_targets(lease.fetch("repos"))
+
+            payload = JSON.generate({
+              "name" => token_name,
+              "scopes" => scopes,
+              "repositories" => repositories
+            }.compact)
+            result = with_secret_header("Authorization: token #{File.read(token_file).strip}") do |header|
+              @runner.call(
+                ["curl", "-sS", "-f", "-X", "POST",
+                  "#{url}/api/v1/admin/users/#{account}/tokens",
+                  "-H", "Content-Type: application/json",
+                  *header,
+                  "-d", payload]
+              )
+            end
+            body = JSON.parse(result)
+            secret = body["sha1"] or raise Providers::TransientError,
+              "forgejo did not return the token secret (check server API version)"
+            validate_granted_scopes(body, scopes)
+
+            {"token" => secret, "token_ref" => token_name,
+             "provider_expiry" => nil,
+             "via" => {"kind" => "file"}}
+          rescue JSON::ParserError
+            raise Providers::TransientError, "forgejo returned an unparseable response"
+          end
+
+          # The lease token is revoked by its server id (the
+          # deterministic token NAME) with the issuer's admin
+          # credential; the secret value is not part of this wire
+          # contract. 404 is the idempotent already-invalid result —
+          # deterministic recovery of an interrupted issue.
+          def revoke(profile:, token_ref:, token: nil)
+            issuer = profile.fetch("issuer")
+            url = issuer["url"] or raise Providers::RefusedError, "forgejo profile has no issuer url"
+            account = issuer["account"] or raise Providers::RefusedError, "forgejo profile has no role account"
+            token_file = issuer["token_file"]
+            _out, err, status = with_secret_header("Authorization: token #{File.read(token_file).strip}") do |header|
+              @capture.call(
+                ["curl", "-sS", "-f", "-X", "DELETE",
+                  "#{url}/api/v1/admin/users/#{account}/tokens/#{token_ref}",
+                  *header]
+              )
+            end
+            return :revoked if status.success?
+            return :already_invalid if err.to_s.match?(/\b404\b/)
+
+            raise Providers::TransientError,
+              "forgejo revoke failed: #{err.to_s.lines.first&.strip}"
+          end
+
+          private
+
+          # RepoTargetOption: {"owner" =>, "name" =>} objects parsed
+          # from `owner/name` entries. An entry without an owner does
+          # not identify a repository — refusing beats issuing an
+          # all-repositories token.
+          def repo_targets(repos)
+            if repos.empty?
+              raise Providers::RefusedError,
+                "an empty repositories payload would mint a token for ALL of the " \
+                "account's repositories — refuse before issuing"
+            end
+
+            repos.map do |entry|
+              owner, name = entry.to_s.split("/", 2)
+              if owner.to_s.empty? || name.to_s.empty?
+                raise Providers::RefusedError,
+                  "repository '#{entry}' is not an identifiable 'owner/name' target — " \
+                  "Forgejo RepoTargetOption requires both; refusing instead of issuing " \
+                  "an all-repositories token"
+              end
+              {"owner" => owner, "name" => name}
+            end
+          end
+
+          # The response's granted scopes (when the server reports
+          # them) must cover the request — the enforced scope is the
+          # server's answer, never the request's claim.
+          def validate_granted_scopes(body, requested)
+            granted = body["scopes"]
+            return unless granted.is_a?(Array)
+
+            missing = requested.map(&:to_s) - granted.map(&:to_s)
+            unless missing.empty?
+              raise Providers::TransientError,
+                "forgejo granted scopes [#{granted.join(', ')}] do not cover the " \
+                "requested [#{missing.join(', ')}]; refusing the grant"
+            end
+          end
+
+          # The Authorization secret NEVER appears in curl argv (visible
+          # in ps): the header value lives in a 0600 ephemeral file for
+          # the duration of one request, passed as `curl -H @file`.
+          def with_secret_header(header)
+            Tempfile.create("ace-lab-curl-header") do |file|
+              file.chmod(0o600)
+              file.write("#{header}\n")
+              file.close
+              yield ["-H", "@#{file.path}"]
+            end
+          end
+
+          def run_curl(argv)
+            out, _err, status = run_capture(argv)
+            raise Providers::TransientError, "forgejo API call failed (curl exit #{status.exitstatus})" unless status.success?
+
+            out
+          end
+
+          def run_capture(argv)
+            Open3.capture3(*argv)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/auth/plugins/github_provider.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+require "base64"
+require "tempfile"
+
+module Ace
+  module Lab
+    module Auth
+      module Plugins
+        # GitHub provider (task 8xs.t.pu0.7): GitHub App JWT →
+        # installation access token for the CHOSEN repositories and
+        # permissions; the response's real `expires_at` becomes the
+        # provider expiry the status reports separately from the
+        # lease's use-until. The App key NEVER reaches the executor;
+        # the issued token is opaque, one per lease. An earlier
+        # use-until than the native expiry requires the host's
+        # scheduled revoke at use_until (DELETE /installation/token —
+        # 401 means the token is already invalid, anything else
+        # network-shaped stays outcome-unknown, never a claimed
+        # revocation).
+        class GithubProvider
+          def initialize(runner: nil, capture: nil)
+            @runner = runner || method(:run_curl)
+            @capture = capture || method(:run_capture)
+          end
+
+          def capabilities
+            {"expiry_mode" => "provider"}
+          end
+
+          def issue(profile:, lease:)
+            issuer = profile.fetch("issuer")
+            base = issuer["api_url"] || "https://api.github.com"
+            installation = issuer["installation_id"] or raise Providers::RefusedError,
+              "github profile has no installation_id"
+            key_file = issuer["key_file"] or raise Providers::RefusedError, "github profile has no key_file reference"
+            app_id = issuer["app_id"] or raise Providers::RefusedError, "github profile has no app_id"
+            raise Providers::RefusedError, "app key file '#{key_file}' is not readable" unless File.readable?(key_file)
+
+            jwt = app_jwt(app_id, File.read(key_file))
+            repos = lease.fetch("repos")
+            if repos.empty?
+              raise Providers::RefusedError,
+                "an empty repository list would mint a token for ALL installation " \
+                "repositories — refuse before issuing"
+            end
+
+            payload = JSON.generate({"repositories" => repos,
+              "permissions" => github_permissions(profile.fetch("scopes"))}.compact)
+            result = with_secret_header("Authorization: Bearer #{jwt}") do |header|
+              @runner.call(
+                ["curl", "-sS", "-f", "-X", "POST",
+                  "#{base}/app/installations/#{installation}/access_tokens",
+                  "-H", "Accept: application/vnd.github+json",
+                  *header,
+                  "-d", payload]
+              )
+            end
+            body = JSON.parse(result)
+            token = body["token"] or raise Providers::TransientError, "github did not return an installation token"
+            {"token" => token, "token_ref" => body["id"].to_s,
+             "provider_expiry" => body["expires_at"],
+             "via" => {"kind" => "file"}}
+          rescue JSON::ParserError
+            raise Providers::TransientError, "github returned an unparseable response"
+          end
+
+          # GitHub revokes the installation token that AUTHENTICATES
+          # the request (DELETE /installation/token -> 204): the
+          # credential is the ISSUED lease token, never a fresh App
+          # JWT - an App JWT names no installation token and revokes
+          # nothing. curl runs with --fail so an HTTP error can never
+          # surface as process success; 401 means the token is already
+          # invalid (an idempotent result), anything else
+          # network-shaped stays outcome-unknown, never a claimed
+          # revocation.
+          def revoke(profile:, token_ref:, token: nil)
+            if token.to_s.empty?
+              raise Providers::OutcomeUnknownError,
+                "the issued installation token (token_ref #{token_ref}) is required to revoke " \
+                "it - GitHub revokes the token that authenticates the request; outcome unknown"
+            end
+
+            issuer = profile.fetch("issuer")
+            base = issuer["api_url"] || "https://api.github.com"
+            _out, err, status = with_secret_header("Authorization: Bearer #{token}") do |header|
+              @capture.call(
+                ["curl", "-sS", "-f", "-X", "DELETE",
+                  "#{base}/installation/token",
+                  "-H", "Accept: application/vnd.github+json",
+                  *header]
+              )
+            end
+            return :revoked if status.success?
+
+            if err.to_s.match?(/\b401\b/)
+              # 401 on the installation endpoint means the token is
+              # already invalid — an idempotent result, not a failure.
+              return :already_invalid
+            end
+
+            raise Providers::OutcomeUnknownError,
+              "github revoke outcome unknown: #{err.to_s.lines.first&.strip}"
+          end
+
+          # No deterministic remote identity: the installation token's
+          # id is only known from the creation RESPONSE — an unknown
+          # issue outcome cannot be settled by reconstruction and must
+          # wait for reconcile/native expiry, never a blind re-mint.
+          def token_ref_for(lease_id:)
+            nil
+          end
+
+          # GitHub's OWN permission schema for installation tokens —
+          # these are the real permission keys of the
+          # POST /app/installations/{id}/access_tokens contract (NOT
+          # Forgejo repository rights): blanket-mapping one provider's
+          # subjects onto the other silently produces permission keys
+          # the endpoint rejects or ignores.
+          INSTALLATION_PERMISSIONS = %w[
+            actions administration checks content_references contents
+            deployments environments issues labels members merge_queues
+            metadata organization_administration organization_custom_org_roles
+            organization_custom_properties organization_hooks
+            organization_packages organization_personal_access_requests
+            organization_personal_access_tokens organization_plan
+            organization_projects organization_rulesets organization_secrets
+            organization_self_hosted_runners organization_user_blocking
+            packages pages pull_requests repository_advisories
+            repository_hooks repository_projects secret_scanning_alerts
+            secrets security_events statuses team_discussions
+            vulnerability_alerts workflows
+          ].freeze
+          PERMISSION_LEVELS = %w[read write admin].freeze
+
+          private
+
+          # The Authorization secret NEVER appears in curl argv (visible
+          # in ps): the header value lives in a 0600 ephemeral file for
+          # the duration of one request, passed as `curl -H @file`.
+          def with_secret_header(header)
+            Tempfile.create("ace-lab-curl-header") do |file|
+              file.chmod(0o600)
+              file.write("#{header}\n")
+              file.close
+              yield ["-H", "@#{file.path}"]
+            end
+          end
+
+          # Profile scopes map onto installation token permissions as
+          # `level:subject` strings validated against GitHub's actual
+          # permission schema (e.g. `write:contents` →
+          # {"contents" => "write"}); the deployment's App installation
+          # must already grant them — the request cannot widen rights.
+          def github_permissions(scopes)
+            scopes.to_h do |scope|
+              level, subject = scope.split(":", 2)
+              subject, level = scope, "read" if subject.nil?
+              if subject.empty? || level.empty? || !PERMISSION_LEVELS.include?(level)
+                raise Providers::RefusedError,
+                  "github scope '#{scope}' is malformed (expected level:subject with " \
+                  "level in #{PERMISSION_LEVELS.join('|')}, e.g. write:contents)"
+              end
+              unless INSTALLATION_PERMISSIONS.include?(subject)
+                raise Providers::RefusedError,
+                  "github scope '#{scope}': '#{subject}' is not a GitHub installation " \
+                  "permission (real examples: contents, pull_requests, members, issues) " \
+                  "— GitHub permission names are not Forgejo repository scopes"
+              end
+
+              [subject, level]
+            end
+          end
+
+          # Minimal RS256 GitHub App JWT (stdlib only): the App key
+          # stays issuer-side; the JWT lives for one request window.
+          def app_jwt(app_id, key_pem)
+            key = OpenSSL::PKey::RSA.new(key_pem)
+            now = Time.now.to_i
+            header = Base64.urlsafe_encode64(JSON.generate({"alg" => "RS256", "typ" => "JWT"}),
+              padding: false)
+            claims = Base64.urlsafe_encode64(JSON.generate({
+              "iat" => now - 60, "exp" => now + 540, "iss" => app_id
+            }), padding: false)
+            signature = Base64.urlsafe_encode64(key.sign("SHA256", "#{header}.#{claims}"),
+              padding: false)
+            "#{header}.#{claims}.#{signature}"
+          end
+
+          def run_curl(argv)
+            out, _err, status = run_capture(argv)
+            raise Providers::TransientError, "github API call failed (exit #{status.exitstatus})" unless status.success?
+
+            out
+          end
+
+          def run_capture(argv)
+            require "open3"
+            Open3.capture3(*argv)
+          end
+        end
+      end
+    end
+  end
+end