ace-lab 0.13.1 → 0.14.0

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

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

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Ace
+  module Lab
+    module Auth
+      # Pure validation/normalization of the trusted auth configuration
+      # (task 8xs.t.pu0.7): the host-owned `auth:` section of the same
+      # root-owned authorization document install converges
+      # (`/etc/lab/ace-lab/authorization.yml`). The existing `principals`
+      # map stays a VISIBILITY map — it never grants token issuance; only
+      # an explicit auth profile does, and a project/coworker config can
+      # only NAME a profile, never widen one.
+      #
+      # A profile declares: provider (forgejo|github|env), the roles and
+      # principals allowed to request it, repos/scopes, ttl (default 30m,
+      # max 60m unless the host sets an explicit profile limit), the
+      # expiry mode (provider | host-revoke | process), and REFERENCES
+      # to issuer credentials (paths — values stay in the host's
+      # protected store). The credential handoff is always the
+      # ephemeral per-lease file (CredentialHandoff) — there is no
+      # configurable handoff style.
+      class ProfileSchema
+        # The bundled providers; an explicitly registered plugin (tests,
+        # host extensions) resolves through the registry at request
+        # time — the schema only demands a concrete provider name.
+        BUNDLED_PROVIDERS = %w[forgejo github env].freeze
+        EXPIRY_MODES = %w[provider host-revoke process].freeze
+        DEFAULT_TTL_MINUTES = 30
+        DEFAULT_MAX_TTL_MINUTES = 60
+        PROFILE_KEYS = %w[provider roles principals repos scopes ttl_minutes max_ttl_minutes
+          expiry_mode issuer env_names].freeze
+
+        class << self
+          # @param document [Hash] parsed authorization document
+          # @return [Hash] {"leases_dir"=>, "credentials_dir"=>,
+          #   "profiles" => {name => normalized profile}}
+          # @raise [Ace::Lab::InvalidConfigurationError]
+          def normalize(document)
+            auth = document["auth"]
+            if auth.nil?
+              return {"leases_dir" => nil, "credentials_dir" => nil, "profiles" => {}}
+            end
+            unless auth.is_a?(Hash)
+              raise Ace::Lab::InvalidConfigurationError, "auth section must be a mapping"
+            end
+
+            profiles = auth["profiles"] || {}
+            unless profiles.is_a?(Hash) && profiles.values.all? { |profile| profile.is_a?(Hash) }
+              raise Ace::Lab::InvalidConfigurationError, "auth profiles must be a mapping of profile names to settings"
+            end
+
+            normalized = profiles.to_h { |name, raw| [name, profile(name, raw)] }
+            {"leases_dir" => optional_path(auth["leases_dir"]),
+             "credentials_dir" => optional_path(auth["credentials_dir"]),
+             "profiles" => normalized}
+          end
+
+          private
+
+          def profile(name, raw)
+            unknown = raw.keys - PROFILE_KEYS
+            unless unknown.empty?
+              raise Ace::Lab::InvalidConfigurationError,
+                "auth profile '#{name}' has unknown key '#{unknown.sort.first}'"
+            end
+
+            provider = required_string(raw, name, "provider")
+
+            roles = string_list(raw["roles"], name, "roles")
+            principals = string_list(raw["principals"], name, "principals")
+            repos = string_list(raw["repos"], name, "repos")
+            ttl = positive_minutes(raw["ttl_minutes"], name, DEFAULT_TTL_MINUTES)
+            max_ttl = positive_minutes(raw["max_ttl_minutes"], name, DEFAULT_MAX_TTL_MINUTES)
+            raise_conflict(name, "ttl_minutes exceeds max_ttl_minutes") if ttl > max_ttl
+
+            expiry_mode = raw["expiry_mode"] || default_expiry_mode(provider)
+            unless EXPIRY_MODES.include?(expiry_mode)
+              raise Ace::Lab::InvalidConfigurationError,
+                "auth profile '#{name}' expiry_mode must be one of: #{EXPIRY_MODES.join(', ')}"
+            end
+            if provider == "env" && expiry_mode != "process" && raw["env_names"] &&
+              raw["issuer"].nil?
+              # A standalone env profile only exposes process-scoped
+              # values; it cannot guarantee remote expiry or revoke.
+              raise Ace::Lab::InvalidConfigurationError,
+                "auth profile '#{name}': a standalone env profile cannot declare " \
+                  "remote expiry/revoke (expiry_mode process only)"
+            end
+
+            {"provider" => provider, "roles" => roles, "principals" => principals,
+             "repos" => repos, "scopes" => string_list(raw["scopes"], name, "scopes"),
+             "ttl_minutes" => ttl, "max_ttl_minutes" => max_ttl,
+             "expiry_mode" => expiry_mode,
+             "issuer" => raw["issuer"].is_a?(Hash) ? raw["issuer"] : {},
+             "env_names" => string_list(raw["env_names"], name, "env_names")}
+          end
+
+          def default_expiry_mode(provider)
+            case provider
+            when "github" then "provider" # installation tokens carry a native expires_at
+            when "forgejo" then "host-revoke" # no native TTL proven across server versions
+            else "process"
+            end
+          end
+
+          def required_string(raw, name, key)
+            value = raw[key]
+            unless value.is_a?(String) && !value.strip.empty?
+              raise Ace::Lab::InvalidConfigurationError,
+                "auth profile '#{name}' key '#{key}' is required"
+            end
+
+            value.strip
+          end
+
+          def string_list(raw, name, key)
+            list = raw.nil? ? [] : raw
+            unless list.is_a?(Array) && list.all? { |entry| entry.is_a?(String) && !entry.strip.empty? }
+              raise Ace::Lab::InvalidConfigurationError,
+                "auth profile '#{name}' key '#{key}' must be a list of non-empty strings"
+            end
+
+            list.map(&:strip).uniq
+          end
+
+          def positive_minutes(raw, name, default)
+            value = raw.nil? ? default : raw
+            unless value.is_a?(Integer) && value.positive?
+              raise Ace::Lab::InvalidConfigurationError,
+                "auth profile '#{name}' ttl must be a positive number of minutes"
+            end
+
+            value
+          end
+
+          def optional_path(raw)
+            return nil if raw.nil?
+            unless raw.is_a?(String) && !raw.strip.empty? && raw.start_with?("/")
+              raise Ace::Lab::InvalidConfigurationError, "auth paths must be absolute"
+            end
+
+            raw.strip
+          end
+
+          def raise_conflict(name, reason)
+            raise Ace::Lab::InvalidConfigurationError, "auth profile '#{name}': #{reason}"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ace
+  module Lab
+    module Auth
+      # Explicit provider registration (task 8xs.t.pu0.7) — the same
+      # precedented pattern as Ace::Git::Providers and the ace-hitl
+      # adapter registry. A plugin owns its protocol; the auth core owns
+      # the contract and the lease lifecycle. No marketplace, no
+      # generic workflow engine.
+      #
+      # Plugin contract (duck type):
+      #   capabilities -> {expiry_mode:} which the profile must accept
+      #   token_ref_for(lease_id:) -> String | nil — the provider's
+      #     DETERMINISTIC remote identity for the lease, written to the
+      #     record at creation; nil when the identity is only knowable
+      #     from the creation response (an unresolved issue then waits
+      #     for reconcile/native expiry instead of deterministic
+      #     settlement)
+      #   issue(profile:, lease:) ->
+      #     {"token" => secret (never serialized), "token_ref" => provider id,
+      #      "provider_expiry" => time-ish | nil, "via" => handoff descriptor}
+      #     or raises RefusedError / TransientError / OutcomeUnknownError
+      #   revoke(profile:, token_ref:, token:) -> :revoked | :already_invalid |
+      #     raises TransientError / OutcomeUnknownError
+      #     (`token` is the issued secret from the handoff — providers
+      #     that revoke BY the token value, e.g. GitHub's installation
+      #     token endpoint, require it; providers revoking by a server
+      #     id ignore it; a 404-shaped unknown id settles as
+      #     :already_invalid so interrupted issues recover
+      #     deterministically)
+      class Providers
+        class RefusedError < StandardError; end
+        class TransientError < StandardError; end
+        class OutcomeUnknownError < StandardError; end
+        class UnsupportedError < StandardError; end
+
+        @registry = {}
+        @mutex = Mutex.new
+
+        class << self
+          def register(name, plugin)
+            @mutex.synchronize { @registry[name.to_s] = plugin }
+          end
+
+          def resolve(name)
+            plugin = @mutex.synchronize { @registry[name.to_s] }
+            raise UnsupportedError, "no auth provider registered for '#{name}'" unless plugin
+
+            plugin
+          end
+
+          def reset!
+            @mutex.synchronize { @registry.clear }
+          end
+
+          def registered
+            @mutex.synchronize { @registry.keys.sort }
+          end
+        end
+      end
+    end
+  end
+end