knoxcall 0.0.1 → 1.0.0

data/lib/knoxcall/bootstrap.rb

@@ -0,0 +1,70 @@
+module KnoxCall
+  # Bootstrap credential types. The +type+ discriminator defaults per class,
+  # so callers never need to spell it out. Secret fields are excluded from
+  # #inspect so a logged client or captured exception context never prints
+  # the secret (Object#to_s is already safe — it shows only class + object id).
+
+  class AccessToken
+    attr_reader :type
+
+    def initialize(access_token:)
+      @access_token = access_token
+      @type = "access_token"
+    end
+
+    def access_token = @access_token
+
+    def inspect = "#<KnoxCall::AccessToken access_token=[REDACTED]>"
+  end
+
+  class OIDCTokenExchange
+    attr_reader :issuer, :type
+
+    def initialize(subject_token:, issuer:)
+      @subject_token = subject_token
+      @issuer = issuer
+      @type = "oidc_token_exchange"
+    end
+
+    def subject_token = @subject_token
+
+    def inspect = "#<KnoxCall::OIDCTokenExchange issuer=#{@issuer.inspect} subject_token=[REDACTED]>"
+  end
+
+  class ClientCredentials
+    attr_reader :client_id, :type
+
+    def initialize(client_id:, client_secret:)
+      @client_id = client_id
+      @client_secret = client_secret
+      @type = "client_credentials"
+    end
+
+    def client_secret = @client_secret
+
+    def inspect = "#<KnoxCall::ClientCredentials client_id=#{@client_id.inspect} client_secret=[REDACTED]>"
+  end
+
+  # Credentials file written by `knoxcall login` (PARITY §2).
+  #
+  # Holds no secrets itself — tokens are read from the file (path/profile
+  # resolved from KNOXCALL_CREDENTIALS_FILE / KNOXCALL_PROFILE when not
+  # given) at token-fetch time, so #inspect stays safe by construction.
+  class StoredCredentials
+    attr_reader :path, :profile, :type
+
+    def initialize(path: nil, profile: nil)
+      @path = path
+      @profile = profile
+      @type = "stored_credentials"
+    end
+
+    def inspect = "#<KnoxCall::StoredCredentials path=#{@path.inspect} profile=#{@profile.inspect}>"
+  end
+
+  # Deprecated aliases — the pre-release *Bootstrap names used by the other
+  # KnoxCall SDKs. Remove before 2.0.
+  AccessTokenBootstrap = AccessToken
+  OidcTokenExchangeBootstrap = OIDCTokenExchange
+  ClientCredentialsBootstrap = ClientCredentials
+end

data/lib/knoxcall/bound_route.rb

@@ -0,0 +1,47 @@
+module KnoxCall
+  # A route with bound call defaults — see Client#route.
+  #
+  #   printnode = client.route("3f1e2c9a-...", environment: "production")
+  #   computers = JSON.parse(printnode.get("/computers").body)
+  #   printnode.post("/printjobs", body: payload)
+  #
+  # Holds only the client reference, route id, and defaults (never a token
+  # or any pipeline state), so retries and 401 re-mint behave exactly as on
+  # Client#call. Per-call values win over bound defaults; headers merge
+  # per-key with per-call winning. A nil per-call value inherits the bound
+  # default — there is no "explicitly clear" mechanism; construct another
+  # handle instead.
+  class BoundRoute
+    def initialize(client, route, environment: nil, headers: {}, timeout: nil)
+      @client = client
+      @route = route
+      @environment = environment
+      @headers = (headers || {}).dup.freeze
+      @timeout = timeout
+      freeze
+    end
+
+    def request(method, path = "/", body: nil, headers: {}, environment: nil, query: nil, timeout: nil)
+      @client.call(
+        @route,
+        method: method,
+        path: path,
+        body: body,
+        headers: @headers.merge(headers || {}),
+        environment: environment.nil? ? @environment : environment,
+        query: query,
+        timeout: timeout.nil? ? @timeout : timeout
+      )
+    end
+
+    def get(path = "/", **kw)    = request("GET", path, **kw)
+    def post(path = "/", **kw)   = request("POST", path, **kw)
+    def put(path = "/", **kw)    = request("PUT", path, **kw)
+    def patch(path = "/", **kw)  = request("PATCH", path, **kw)
+    def delete(path = "/", **kw) = request("DELETE", path, **kw)
+
+    def inspect
+      "#<KnoxCall::BoundRoute route=#{@route.inspect} environment=#{@environment.inspect}>"
+    end
+  end
+end

data/lib/knoxcall/cli/ai.rb

@@ -0,0 +1,79 @@
+module KnoxCall
+  module CLI
+    # `knoxcall ai exchange` — RFC 8693 workload federation from a terminal.
+    #
+    # Mirrors knoxcall-python's knoxcall/cli/ai.py (the PARITY §13 reference):
+    # same flags, same messages, same exit codes.
+    #
+    # The one KnoxCall command that needs no `knoxcall login` and no KnoxCall
+    # credential at all: the CI workload's own OIDC id_token IS the credential,
+    # and the server verifies it against the issuer's published JWKS.
+    #
+    #   export KC_TOKEN="$(knoxcall ai exchange --tenant acme)"
+    #
+    # Two rules this command exists to enforce, because both are easy to get
+    # wrong in a CI script and neither fails in a way that names itself:
+    #
+    #   1. The subject token is read from the environment, NEVER a flag. An argv
+    #      value lands in shell history, in +ps+ output, and in the CI log line
+    #      that echoes the command. Same rule +knoxcall init+ applies to
+    #      KNOXCALL_WRAP_SECRET.
+    #   2. The host is the tenant data plane, and there is no default. On
+    #      api.knoxcall.com this endpoint answers 401, which reads as "my CI
+    #      token was rejected" and sends people hunting through their issuer's
+    #      JWKS.
+    #
+    # Only the token goes to stdout, so <tt>$(...)</tt> captures exactly the
+    # token.
+    module Ai
+      # The subject token is read from here, never from argv. See rule 1 above.
+      SUBJECT_TOKEN_ENV = "KNOXCALL_SUBJECT_TOKEN".freeze
+
+      module_function
+
+      def run(options)
+        subject_token = (ENV[SUBJECT_TOKEN_ENV] || "").strip
+        if subject_token.empty?
+          raise Error,
+                "#{SUBJECT_TOKEN_ENV} is not set — put your CI provider's OIDC id_token there " \
+                "(a flag would land in shell history, ps output and the CI log). GitHub Actions: " \
+                "request one with `id-token: write` and the ACTIONS_ID_TOKEN_REQUEST_URL endpoint, " \
+                'audience "knoxcall:gateway".'
+        end
+
+        tenant = options[:tenant]
+        base_url = options[:base_url]
+        if (tenant.nil? || tenant.empty?) && (base_url.nil? || base_url.empty?)
+          raise Error,
+                "one of --tenant or --base-url is required: POST /v1/oauth/token is served only on " \
+                "the tenant data-plane host (https://{tenant}.knoxcall.com). Pointing it at " \
+                "api.knoxcall.com answers 401, which reads like a rejected subject_token but means " \
+                "the endpoint is not there."
+        end
+
+        kwargs = {
+          subject_token: subject_token,
+          tenant: tenant,
+          sandbox: options[:sandbox] == true,
+          base_url: base_url
+        }
+        # `resource` is only passed when the flag was GIVEN: the SDK
+        # distinguishes nil from an empty string, and an empty one is a server
+        # refusal rather than "no resource".
+        kwargs[:resource] = options[:resource] if options.key?(:resource)
+        kwargs[:audience] = options[:audience] if options[:audience]
+
+        result = KnoxCall.exchange_token(**kwargs)
+        token = result["access_token"]
+        raise Error, "the exchange returned no access_token" if token.nil? || token.empty?
+
+        # stdout: the token, nothing else. stderr: everything a human wants.
+        puts token
+        kind = options.key?(:resource) ? "tool (MCP, resource-bound)" : "agent"
+        ttl = result["expires_in"].is_a?(Integer) ? ", valid #{result['expires_in']}s" : ""
+        warn "exchanged for a #{kind} token#{ttl}"
+        0
+      end
+    end
+  end
+end

data/lib/knoxcall/cli/ai_control.rb

@@ -0,0 +1,275 @@
+module KnoxCall
+  module CLI
+    # `knoxcall ai` — the AI-gateway CONTROL plane from a terminal (AIGW-162).
+    #
+    # Mirrors the Node reference (sdk/knoxcall-node/src/cli/ai-control.ts):
+    # same flags, same messages, same stdout/stderr split, same exit codes.
+    #
+    # `ai exchange` (ai.rb) is the data-plane door: it needs no login, because
+    # the CI workload's OIDC token IS the credential. Everything here is the
+    # opposite — it acts as the signed-in tenant, through the same
+    # ~/.knoxcall/credentials.json profile `login` writes and `whoami` reads.
+    #
+    # WHY THIS EXISTS. Until now the five SDK CLIs shipped exactly one `ai`
+    # sub-command, `exchange`. A capable `knoxcall ai gateways|agents|mint|usage`
+    # lived in a standalone `cli/` package that was never published, never
+    # tested, never in CI and not in the workspaces — and it could not create a
+    # secret, a gateway or an agent, so it could not get you to a first call
+    # either. So there was no CLI golden path at all: the only way from "I have
+    # an API key" to "my app is calling an LLM through KnoxCall" was the browser
+    # or hand-written HTTP.
+    #
+    # The golden path these commands exist to make true, from a tenant with
+    # nothing in it:
+    #
+    #     export ANTHROPIC_API_KEY=sk-ant-...
+    #     knoxcall ai create-agent --name copilot --slug copilot \
+    #         --provider anthropic --secret-from-env ANTHROPIC_API_KEY
+    #     knoxcall ai mint --agent <id>
+    #     curl "$AGENT_URL/v1/messages" -H "Authorization: Bearer $TOKEN" ...
+    #
+    # Two commands, then a real streamed call. +create-agent+ prints the agent
+    # id, the +agent_url+ and the exact next command, so the path is
+    # discoverable without re-reading the docs.
+    #
+    # THREE RULES, each one a bug this shape invites:
+    #
+    #   1. A PROVIDER KEY IS NEVER AN ARGV VALUE. +--secret-from-env NAME+ names
+    #      the environment variable to read; there is deliberately no
+    #      +--secret-value+. An argv value lands in shell history, in +ps+
+    #      output and in the CI log line that echoes the command. Same rule
+    #      +ai exchange+ applies to KNOXCALL_SUBJECT_TOKEN and +init+ to
+    #      KNOXCALL_WRAP_SECRET.
+    #
+    #   2. NO POSITIONAL ARGUMENTS. Four of the five SDK CLIs hand-roll their
+    #      parser and reject positionals outright; only python gets them free
+    #      from argparse. Ids are flags (+--gateway+, +--agent+) so the surface
+    #      is the same in all five rather than "the same except in Ruby".
+    #
+    #   3. AN AGENT WITHOUT AN UPSTREAM IS REFUSED HERE, not at its first call.
+    #      The API accepts create_agent with no provider/upstream_secret_id and
+    #      stores an agent whose first data-plane request 502s (AIGW-161). A
+    #      command whose entire purpose is "get me to a working call" must not
+    #      be able to produce that, so +--provider+ and one of +--secret+ /
+    #      +--secret-from-env+ are required together.
+    #
+    # No HTTP lives here: every call goes through the typed SDK resources
+    # (client.ai_gateway, client.secrets).
+    module AiControl
+      module_function
+
+      # A client acting as the signed-in tenant, or a refusal telling them to
+      # log in. Obtained exactly the way `whoami` and `init` obtain theirs.
+      def client_for(options)
+        path = CredentialsFile.resolve_path
+        profile = CredentialsFile.resolve_profile(options[:profile])
+        if CredentialsFile.read_profile(path, profile).nil?
+          raise Error, "not logged in (profile '#{profile}') — run `knoxcall login`"
+        end
+
+        client_opts = { bootstrap: StoredCredentials.new(path: path, profile: profile) }
+        client_opts[:base_url] = options[:base_url] if presence(options[:base_url])
+        client_opts[:sandbox] = true if options[:sandbox]
+        Client.new(**client_opts)
+      end
+
+      def presence(value) = CredentialsFile.presence(value)
+
+      def required(value, flag)
+        found = presence(value)
+        raise Error, "#{flag} is required" if found.nil?
+
+        found
+      end
+
+      # -- knoxcall ai gateways -------------------------------------------------
+
+      def gateways(options)
+        client = client_for(options)
+        rows = client.ai_gateway.list_gateways(per_page: 100)["data"] || []
+        if rows.empty?
+          warn "No AI gateways. `knoxcall ai create-agent` will create one for you."
+          return 0
+        end
+
+        rows.each { |g| puts "#{g['id']}  #{g['slug']}  #{g['name']}" }
+        0
+      end
+
+      # -- knoxcall ai agents --gateway ID --------------------------------------
+
+      def agents(options)
+        gateway_id = required(options[:gateway], "--gateway")
+        client = client_for(options)
+        rows = client.ai_gateway.list_agents(gateway_id, per_page: 100)["data"] || []
+        if rows.empty?
+          warn "No agents in that gateway."
+          return 0
+        end
+
+        # agent_url is on every projection since AIGW-161, so a list is enough
+        # to point an SDK at an existing agent — no follow-up GET.
+        rows.each { |a| puts "#{a['id']}  #{a['slug']}  #{a['agent_url']}" }
+        0
+      end
+
+      # -- knoxcall ai create-agent ---------------------------------------------
+
+      def create_agent(options)
+        slug = required(options[:slug], "--slug")
+        # Rule 3: refuse here rather than let the API store an agent with no
+        # upstream whose first data-plane call 502s.
+        provider = required(options[:provider], "--provider")
+        if presence(options[:secret]).nil? && presence(options[:secret_from_env]).nil?
+          raise Error,
+                "one of --secret or --secret-from-env is required: an agent created without an " \
+                "upstream credential is accepted by the API and 502s on its first call."
+        end
+
+        client = client_for(options)
+        gateway_id = resolve_gateway(client, options[:gateway])
+        secret_id = resolve_secret(client, options)
+
+        body = {
+          name: presence(options[:name]) || slug,
+          slug: slug,
+          provider: provider,
+          upstream_secret_id: secret_id
+        }
+        body[:upstream] = options[:upstream] if presence(options[:upstream])
+        body[:default_model] = options[:model] if presence(options[:model])
+        agent = client.ai_gateway.create_agent(gateway_id, **body)
+
+        # stdout: the agent id, so $(...) captures exactly that. Everything a
+        # human needs next goes to stderr, including the command that follows.
+        puts agent["id"]
+        warn "\n  agent:     #{agent['slug']} (#{agent['id']})"
+        warn "  gateway:   #{gateway_id}"
+        warn "  provider:  #{provider}"
+        warn "  base_url:  #{agent['agent_url']}" if presence(agent["agent_url"])
+        warn "\n  Next:  knoxcall ai mint --agent #{agent['id']}"
+        0
+      end
+
+      # Resolve the gateway to create under.
+      #
+      # +--gateway+ takes an id OR a slug. With no +--gateway+: use the tenant's
+      # only gateway, or create one when they have none — that is what makes the
+      # command work on a fresh tenant, which is the whole point. With SEVERAL
+      # and no flag it refuses and lists them rather than picking: "whichever
+      # sorts first" is how the quickstart wizard silently landed a second agent
+      # in the wrong gateway.
+      def resolve_gateway(client, wanted)
+        rows = client.ai_gateway.list_gateways(per_page: 100)["data"] || []
+        wanted = presence(wanted)
+        if wanted
+          hit = rows.find { |g| g["id"] == wanted || g["slug"] == wanted }
+          raise Error, "no gateway '#{wanted}' — this tenant has: #{gateway_list(rows)}" if hit.nil?
+
+          return hit["id"]
+        end
+        return rows.first["id"] if rows.length == 1
+
+        if rows.empty?
+          created = client.ai_gateway.create_gateway(name: "Default", slug: "default")
+          warn "created gateway #{created['slug']} (#{created['id']})"
+          return created["id"]
+        end
+
+        raise Error,
+              "--gateway is required: this tenant has #{rows.length} gateways " \
+              "(#{gateway_list(rows)}). Picking one for you would put the agent somewhere " \
+              "you did not choose."
+      end
+
+      def gateway_list(rows)
+        listed = rows.map { |g| "#{g['slug']} (#{g['id']})" }.join(", ")
+        listed.empty? ? "none" : listed
+      end
+
+      # Resolve the upstream secret, escrowing one from the environment if asked.
+      #
+      # The key is read from ENV[NAME], never from a flag — see rule 1.
+      # Re-running with the same +--secret-from-env+ reuses the existing secret
+      # by name rather than creating a second copy of the same credential.
+      def resolve_secret(client, options)
+        secret = presence(options[:secret])
+        return secret if secret
+
+        env_name = required(options[:secret_from_env], "--secret or --secret-from-env")
+        value = (ENV[env_name] || "").strip
+        if value.empty?
+          raise Error,
+                "#{env_name} is not set — put your provider key there. There is deliberately no " \
+                "--secret-value flag: an argv value lands in shell history, ps output and the CI log."
+        end
+
+        name = "ai-gateway-#{presence(options[:slug]) || 'agent'}-key"
+        hit = (client.secrets.list(per_page: 100)["data"] || []).find { |s| s["name"] == name }
+        if hit
+          warn "reusing secret '#{name}' (#{hit['id']})"
+          return hit["id"]
+        end
+
+        created = client.secrets.create(name: name, value: value)
+        warn "escrowed secret '#{name}' (#{created['id']}) — the key is now in KnoxCall custody"
+        created["id"]
+      end
+
+      # -- knoxcall ai mint --agent ID ------------------------------------------
+
+      def mint(options)
+        agent_id = required(options[:agent], "--agent")
+        client = client_for(options)
+        body = {}
+        body[:kind] = options[:kind] if presence(options[:kind])
+        body[:name] = options[:name] if presence(options[:name])
+        minted = client.ai_gateway.mint_token(agent_id, **body)
+
+        # The plaintext is returned ONCE. stdout carries only the token so
+        # `> token.txt` captures the token and nothing else; the metadata and
+        # the warning go to stderr.
+        puts minted["token"]
+        warn "\n  id:       #{minted['id']}"
+        warn "  kind:     #{minted['kind']}"
+        warn "  prefix:   #{minted['prefix']}"
+        warn "  dpop:     #{minted['dpop_required']}"
+        warn "  expires:  #{minted['expires_at'] || 'never'}"
+        warn "\n  Save this token now — it will not be shown again."
+        0
+      end
+
+      # -- knoxcall ai usage ----------------------------------------------------
+
+      def usage(options)
+        client = client_for(options)
+        agent_id = presence(options[:agent])
+        params = { period: presence(options[:period]) || "30d" }
+        params[:agent_id] = agent_id if agent_id
+        rollup = client.ai_gateway.usage(**params)
+        totals = rollup["totals"] || {}
+
+        puts "Usage — last #{rollup['period_days']} days#{agent_id ? " (agent #{agent_id})" : ''}"
+        puts "  requests:      #{totals['requests']}"
+        puts "  input tokens:  #{totals['input_tokens']}"
+        puts "  output tokens: #{totals['output_tokens']}"
+        puts format("  cost (USD):    %.4f", totals["cost_usd"].to_f)
+        puts "  unpriced:      #{totals['unpriced_requests']}"
+
+        by_model = rollup["by_model"] || []
+        if by_model.empty?
+          puts "\nNo usage in this period."
+          return 0
+        end
+
+        puts "\nBy model:"
+        by_model.each do |m|
+          puts format("  %s/%s  %s req  in %s  out %s  $%.4f",
+                      m["provider"], m["model"], m["requests"],
+                      m["input_tokens"], m["output_tokens"], m["cost_usd"].to_f)
+        end
+        0
+      end
+    end
+  end
+end

data/lib/knoxcall/cli/common.rb

@@ -0,0 +1,96 @@
+require "json"
+require "net/http"
+require "uri"
+require "fileutils"
+
+module KnoxCall
+  module CLI
+    # Reserved alias accepted by /oauth/authorize and the device endpoints; the
+    # server lazily provisions the tenant's real CLI client and returns its id
+    # as the +client_id+ extension member on the token response.
+    CLI_CLIENT_ID = "knoxcall-cli"
+
+    # Expected CLI failure — printed as a one-line message, never a backtrace.
+    class Error < StandardError; end
+
+    # Shared CLI plumbing — token-endpoint POSTs, profile persistence.
+    module Common
+      module_function
+
+      # POST a urlencoded form; return [status, parsed-JSON-or-empty-hash].
+      #
+      # Connection failures raise CLI::Error with a human message. HTTP error
+      # statuses are returned, not raised — device polling needs the error codes.
+      def post_form(url, form, timeout: 30)
+        uri = URI.parse(url)
+        req = Net::HTTP::Post.new(uri)
+        req["Content-Type"] = "application/x-www-form-urlencoded"
+        req["Accept"] = "application/json"
+        req["User-Agent"] = SDK_VERSION
+        req.body = URI.encode_www_form(form)
+
+        resp = begin
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = uri.scheme == "https"
+          http.open_timeout = timeout
+          http.read_timeout = timeout
+          http.start { |h| h.request(req) }
+        rescue Net::OpenTimeout, Net::ReadTimeout, OpenSSL::SSL::SSLError,
+               EOFError, SocketError, SystemCallError, IOError => e
+          raise Error, "could not reach #{url}: #{e.message}"
+        end
+
+        body = begin
+          JSON.parse(resp.body.to_s)
+        rescue JSON::ParserError
+          nil
+        end
+        [resp.code.to_i, body.is_a?(Hash) ? body : {}]
+      end
+
+      def token_error_message(status, body)
+        detail = CredentialsFile.presence(body["error_description"]) ||
+                 CredentialsFile.presence(body["error"]) || "HTTP #{status}"
+        "sign-in failed: #{detail}"
+      end
+
+      # Store a successful token response as a credentials-file profile.
+      #
+      # Persists the +tenant+ and +client_id+ extension members — refreshes
+      # must use the REAL per-tenant client id, not the +knoxcall-cli+ alias.
+      # The write happens UNDER the cross-process file lock so a login racing
+      # a concurrent refresh never loses a rotation.
+      def persist_login(path:, profile:, base_url:, token_body:, fallback_tenant: nil)
+        expires_in = begin
+          Float(token_body["expires_in"] || 3600)
+        rescue ArgumentError, TypeError
+          3600.0
+        end
+        record = {
+          "tenant" => CredentialsFile.presence(token_body["tenant"]) || fallback_tenant,
+          "base_url" => base_url,
+          "client_id" => CredentialsFile.presence(token_body["client_id"]) || CLI_CLIENT_ID,
+          "refresh_token" => token_body["refresh_token"],
+          "access_token" => token_body["access_token"],
+          "access_token_expires_at" => CredentialsFile.format_expiry(Time.now + expires_in),
+          "scope" => token_body["scope"] || ""
+        }
+        # The lock file lives next to the target — on a first-ever login the
+        # directory does not exist yet, so create it before acquiring.
+        FileUtils.mkdir_p(File.dirname(path), mode: 0o700)
+        CredentialsFile::Lock.new(path).with_lock do
+          CredentialsFile.write_profile(path, profile, record)
+        end
+        record
+      end
+
+      # Default management base: KNOXCALL_BASE_URL env > (sandbox|production)
+      # host. An explicit --base-url beats both (handled by the caller).
+      def default_base_url(sandbox)
+        env = ENV["KNOXCALL_BASE_URL"]
+        return env if env && !env.empty?
+        sandbox ? "https://sandbox.#{DEFAULT_CLOUD_HOST}" : DEFAULT_API_BASE
+      end
+    end
+  end
+end

data/lib/knoxcall/cli/init.rb

@@ -0,0 +1,94 @@
+module KnoxCall
+  module CLI
+    # `knoxcall init` — get started wrapping a provider SDK through KnoxCall
+    # (sdk-wrapping #17.4; PARITY §13). Mirrors the Node reference (src/cli/init.ts).
+    #
+    # SAFE BY DESIGN — this does NOT provision a tenant. It works against the
+    # tenant you are already signed in to (`knoxcall login`). Two modes:
+    #
+    #   knoxcall init
+    #       Scaffold mode: confirm who you're signed in as and print a two-step
+    #       wrap quickstart. No writes.
+    #
+    #   knoxcall init --provider stripe --secret-name wrap-stripe --host api.stripe.com
+    #       One-shot escrow: move a provider key into KnoxCall custody and print
+    #       the gateway base_url to point your SDK at. The KEY is read from the
+    #       KNOXCALL_WRAP_SECRET env var (never a flag) so it stays out of your
+    #       shell history/argv. Escrow is idempotent-ish server-side (409 on a
+    #       duplicate name).
+    #
+    # Tenant provisioning + a fully headless one-shot flow are a deliberate
+    # follow-up — a CLI that mints tenants is a bigger, riskier surface.
+    module Init
+      module_function
+
+      def run(options)
+        # Auth: reuse the stored login. Never provision.
+        path = CredentialsFile.resolve_path
+        profile = CredentialsFile.resolve_profile(options[:profile])
+        if CredentialsFile.read_profile(path, profile).nil?
+          raise Error, "not logged in (profile '#{profile}') — run `knoxcall login` first"
+        end
+
+        client_opts = { bootstrap: StoredCredentials.new(path: path, profile: profile) }
+        client_opts[:base_url] = options[:base_url] if CredentialsFile.presence(options[:base_url])
+        client_opts[:sandbox] = true if options[:sandbox]
+        client = Client.new(**client_opts)
+
+        account = client.account.get || {}
+        tenant = CredentialsFile.presence(account["name"]) ||
+                 CredentialsFile.presence(account["company_name"]) ||
+                 CredentialsFile.presence(account["slug"]) || "(unknown)"
+        puts "Signed in as #{tenant}."
+
+        # One-shot escrow mode: --provider selects it; the other bits are then required.
+        if CredentialsFile.presence(options[:provider])
+          return escrow_mode(client, options)
+        end
+
+        scaffold_mode
+      end
+
+      # One-shot escrow: escrow the key (read from KNOXCALL_WRAP_SECRET, never a
+      # flag) then mint the gateway base_url. The raw key is never printed.
+      def escrow_mode(client, options)
+        name = options[:secret_name].to_s.strip
+        host = options[:host].to_s.strip.downcase
+        value = ENV["KNOXCALL_WRAP_SECRET"]
+        raise Error, "--secret-name is required with --provider" if name.empty?
+        raise Error, "--host is required with --provider" if host.empty?
+        if value.nil? || value.empty?
+          raise Error, "set the provider key in the KNOXCALL_WRAP_SECRET env var (not a flag)"
+        end
+
+        client.wrap.escrow(provider: options[:provider], name: name, value: value, hosts: [host])
+        res = client.wrap.gateway_url(secret: name, host: host)
+        puts ""
+        puts "Escrowed '#{name}' for #{host} — your provider key is now in KnoxCall custody."
+        puts "Point a base-URL-only SDK at:"
+        puts "  #{res['base_url']}"
+        puts ""
+        puts "…or transport-wrap an SDK that takes an injected Faraday connection:"
+        puts "  knox = KnoxCall::Client.new  # your KnoxCall key"
+        puts "  conn = knox.wrap.faraday_connection(url: \"https://#{host}\")"
+        0
+      end
+
+      # Scaffold mode: print the two-step quickstart, no writes.
+      def scaffold_mode
+        puts ""
+        puts "Wrap a provider SDK through KnoxCall in two steps:"
+        puts ""
+        puts "1) Move the provider key into custody (key via KNOXCALL_WRAP_SECRET):"
+        puts "   KNOXCALL_WRAP_SECRET=sk_live_… \\"
+        puts "   knoxcall init --provider stripe --secret-name wrap-stripe --host api.stripe.com"
+        puts ""
+        puts "2) Route your SDK through KnoxCall (the key never re-enters your process):"
+        puts "   knox = KnoxCall::Client.new  # your KnoxCall key"
+        puts "   conn = knox.wrap.faraday_connection(url: \"https://api.stripe.com\")"
+        puts "   # …or point a base-URL-only SDK at the base_url that step 1 prints."
+        0
+      end
+    end
+  end
+end