Developer SDK

Ruby examples

Install the SDK · View source on GitHub ↗

embed/selftest.rb

ruby
# frozen_string_literal: true

# The credential-free self-test (EMBED_CONTRACT.md, "Self-test"). It checks
# the golden vectors and status rules, the data fields, the cap object, the
# JWT claim, the token fetch against a stand-in server, the installation
# state files and the configuration exit codes without a network,
# credentials, a device or the native SDK. `main.rb --self-test` runs every
# check; embed_test.rb runs each one as a test.

require "fileutils"
require "json"
require "stringio"
require "tmpdir"
require_relative "commands"

module Embed
  # The self-test checks.
  module SelfTest
    # A self-test check that failed.
    class Failure < StandardError; end

    TEST_CLIENT_ID = "11111111-1111-1111-1111-111111111111"
    TEST_OTHER_CLIENT_ID = "22222222-2222-2222-2222-222222222222"
    TEST_INSTANCE_ID = "33333333-3333-3333-3333-333333333333"
    TEST_TOKEN_SERVER = "http://127.0.0.1:8790"
    TEST_API = "http://127.0.0.1:8791"
    # a stand-in demo session; real sessions come from your service's sign-in
    TEST_SESSION = "self-test-demo-session-0123456789abcdef"

    # 2026-10-06 19:05:00.000 UTC
    TEST_RETRY_TIME = 1_791_313_500_000

    # the settings that run reads
    EMBED_SETTINGS = %w[URNETWORK_EMBED_STATE_DIR URNETWORK_TOKEN_SERVER_URL URNETWORK_DEMO_SESSION URNETWORK_API_URL].freeze

    CHECKS = %i[
      check_byte_vectors
      check_reset_vectors
      check_client_limit_vectors
      check_status_lines
      check_status_rules
      check_data_fields
      check_cap_parsing
      check_sdk_status_json
      check_client_jwt_claims
      check_origins
      check_token_fetch
      check_state_files
      check_config_errors
      check_start_line
    ].freeze

    # A stand-in for the token server and the API: a transport callable that
    # logs each request and answers from a queue of [status, body] answers. An
    # answer that is a TransportError is raised, as an unreachable server.
    class StandInServer
      attr_reader :requests

      def initialize(*answers)
        @answers = answers
        @requests = []
      end

      def call(method, url, headers, body)
        @requests << {method: method, url: url, headers: headers.dup, body: body}
        answer = @answers.shift
        raise Failure, "unexpected request #{method} #{url}" if answer.nil?
        raise answer if answer.is_a?(Exception)

        status, value = answer
        [status, value.is_a?(String) ? value : JSON.generate(value)]
      end
    end

    module_function

    # Runs every check and raises the first failure.
    def run
      CHECKS.each { |check| public_send(check) }
    end

    # An unsigned JWT with payload_json as its claims, for the claim checks only.
    def self_test_jwt(payload_json)
      segment = ->(text) { [text].pack("m0").tr("+/", "-_").delete("=") }
      "#{segment.call('{"alg":"none"}')}.#{segment.call(payload_json)}.c2lnbmF0dXJl"
    end

    def test_client_jwt
      self_test_jwt(%({"client_id":"#{TEST_CLIENT_ID}"}))
    end

    # A cap reading from cap object fields, through the real parser.
    def cap_reading(**fields)
      reading = Caps.parse_cap_object({"client_id" => TEST_CLIENT_ID}.merge(fields.transform_keys(&:to_s)))
      raise Failure, "the self-test's own cap object does not parse: #{fields}" if reading.nil?

      reading
    end

    def expect(condition, message)
      raise Failure, message unless condition
    end

    # Raises Failure unless the block raises error_class.
    def expect_raises(error_class, message)
      yield
    rescue error_class
      nil
    rescue StandardError => error
      raise Failure, "#{message}: raised #{error.class} instead"
    else
      raise Failure, message
    end

    # A private temporary directory (0700), removed afterwards.
    def private_dir
      Dir.mktmpdir("ur-embed-self-test-") do |directory|
        File.chmod(0o700, directory) if State::POSIX
        yield directory
      end
    end

    # The embed settings set to values, and the other embed settings unset,
    # for the duration; the previous environment is restored afterwards.
    def embed_environment(values)
      saved = EMBED_SETTINGS.to_h { |name| [name, ENV.fetch(name, nil)] }
      EMBED_SETTINGS.each { |name| ENV.delete(name) }
      values.each { |name, value| ENV[name] = value }
      yield
    ensure
      saved.each { |name, value| value.nil? ? ENV.delete(name) : ENV[name] = value }
    end

    # Runs the block with $stdout and $stderr captured; returns the block's
    # value and the captured text.
    def captured
      out = StringIO.new
      saved_out, saved_err = $stdout, $stderr
      $stdout = out
      $stderr = out
      [yield, out.string]
    ensure
      $stdout, $stderr = saved_out, saved_err
    end

    # A token server success answer.
    def token_answer(client_id: TEST_CLIENT_ID, client_jwt: test_client_jwt, data_cap: :default)
      data_cap = {"client_id" => client_id, "monthly_byte_limit" => 10_000_000_000, "monthly_used_byte_count" => 0} if data_cap == :default
      {"client_id" => client_id, "by_client_jwt" => client_jwt, "data_cap" => data_cap}
    end

    # Data amounts use decimal units, one decimal, ties to even on the exact
    # integer.
    def check_byte_vectors
      [
        [0, "0 B"],
        [999, "999 B"],
        [1000, "1.0 kB"],
        [999_949, "999.9 kB"],
        # exact halves round to even on the integer; rounding the binary value
        # of 1.05, just above 1.05, would give 1.1
        [1050, "1.0 kB"],
        [1150, "1.2 kB"],
        [1250, "1.2 kB"],
        [1750, "1.8 kB"],
        # 999.95 kB ties to the even 1000.0 kB and moves to the next unit, as does 999.999 kB
        [999_950, "1.0 MB"],
        [999_999, "1.0 MB"],
        [1_234_567_890, "1.2 GB"],
        [5_000_000_000, "5.0 GB"],
        [10_000_000_000, "10.0 GB"],
        [3_000_000_000_000, "3.0 TB"],
        [9_223_372_036_854_775_807, "9.2 EB"],
      ].each do |byte_count, text|
        actual = Embed.format_byte_count(byte_count)
        expect(actual == text, "#{byte_count} bytes format as #{actual.inspect}, want #{text.inspect}")
      end
    end

    # The monthly reset time is in UTC with the seconds rounded up; text that
    # does not parse has no reset time.
    def check_reset_vectors
      [
        ["2026-11-01T00:00:00Z", "resets 2026-11-01 00:00 UTC"],
        # rounds up to the next whole minute
        ["2026-10-31T23:59:00.001Z", "resets 2026-11-01 00:00 UTC"],
        # converted to UTC
        ["2026-10-31T19:00:00-05:00", "resets 2026-11-01 00:00 UTC"],
        ["2026-10-31T23:59:59.999999999Z", "resets 2026-11-01 00:00 UTC"],
        # rounding up rolls over the day and the year
        ["2026-12-31T23:59:30+00:00", "resets 2027-01-01 00:00 UTC"],
      ].each do |period_end, text|
        actual = Embed.reset_time_text(period_end)
        expect(actual == text, "#{period_end.inspect} resets as #{actual.inspect}, want #{text.inspect}")
      end
      ["", "2026-11-01", "not a time", "2026-13-01T00:00:00Z", "2026-02-30T00:00:00Z", "2026-11-01T00:00:00"].each do |unparsed|
        expect(Embed.reset_time_text(unparsed).nil?, "#{unparsed.inspect} must not parse as a reset time")
      end
    end

    # The client limit status names the SDK's retry time in UTC, rounded up.
    def check_client_limit_vectors
      [
        [TEST_RETRY_TIME, "client limit, retry at 19:05 UTC"],
        # 19:04:00.001 UTC rounds up
        [1_791_313_440_001, "client limit, retry at 19:05 UTC"],
        [0, "client limit"],
      ].each do |retry_time, text|
        actual = Embed.client_limit_text(retry_time)
        expect(actual == text, "retry #{retry_time} shows #{actual.inspect}, want #{text.inspect}")
      end
    end

    # The contract's console status line vectors.
    def check_status_lines
      failed = CapState.new
      failed.record(nil)
      # the first reading answers the Embed-not-enabled refusal; and a capped
      # monthly reading, then the refusal
      refused = CapState.new
      refused.record(EMBED_NOT_ENABLED)
      cleared = CapState.new(cap_reading(monthly_byte_limit: 5_000_000_000, monthly_used_byte_count: 5_000_000_000,
                                         monthly_period_end: "2026-11-01T00:00:00Z", capped: true, capped_reason: CAPPED_REASON_MONTHLY))
      cleared.record(EMBED_NOT_ENABLED)
      [
        # connecting, caps not read yet
        ["", 0, CapState.new, 0, "status: connecting | data this month: checking | data total: checking"],
        ["", 0, CapState.new(cap_reading(monthly_byte_limit: 5_000_000_000, monthly_used_byte_count: 1_234_567_890, total_byte_limit: nil)), 1,
         "status: connected | data this month: 1.2 GB of 5.0 GB | data total: no cap"],
        ["", 0, failed, 1, "status: connected | data this month: unavailable | data total: unavailable"],
        ["", 0, refused, 1, "status: connected | data this month: unavailable | data total: unavailable"],
        ["", 0, cleared, 1, "status: connected | data this month: unavailable | data total: unavailable"],
        ["", 0, CapState.new(cap_reading(monthly_byte_limit: 5_000_000_000, monthly_used_byte_count: 5_000_000_000,
                                         monthly_period_end: "2026-11-01T00:00:00Z", capped: true, capped_reason: CAPPED_REASON_MONTHLY)), 3,
         "status: data cap reached, resets 2026-11-01 00:00 UTC | data this month: 5.0 GB of 5.0 GB | data total: no cap"],
        ["", 0, CapState.new(cap_reading(total_byte_limit: 10_000_000_000, total_used_byte_count: 10_000_000_000,
                                         capped: true, capped_reason: CAPPED_REASON_TOTAL)), 3,
         "status: data cap reached | data this month: no cap | data total: 10.0 GB of 10.0 GB"],
        ["", 0, CapState.new(cap_reading(monthly_byte_limit: 0, monthly_used_byte_count: 0, capped: true, capped_reason: CAPPED_REASON_MONTHLY)), 3,
         "status: paused | data this month: 0 B of 0 B | data total: no cap"],
        [CLIENT_LIMIT_STATUS_EXCEEDED, TEST_RETRY_TIME, CapState.new(cap_reading(monthly_byte_limit: 5_000_000_000, monthly_used_byte_count: 0)), 0,
         "status: client limit, retry at 19:05 UTC | data this month: 0 B of 5.0 GB | data total: no cap"],
      ].each do |client_limit_status, retry_time, cap_state, providers_added, line|
        actual = Embed.status_snapshot(true, false, client_limit_status, retry_time, cap_state, providers_added).line
        expect(actual == line, "status line #{actual.inspect}, want #{line.inspect}")
      end
    end

    # The contract's status rule vectors, in rule order.
    def check_status_rules
      capped_monthly_zero = cap_reading(monthly_byte_limit: 0, capped: true, capped_reason: CAPPED_REASON_MONTHLY)
      capped_total_zero = cap_reading(total_byte_limit: 0, monthly_byte_limit: 5_000_000_000, capped: true, capped_reason: CAPPED_REASON_TOTAL)
      capped_monthly = cap_reading(monthly_byte_limit: 5_000_000_000, monthly_period_end: "2026-11-01T00:00:00Z", capped: true, capped_reason: CAPPED_REASON_MONTHLY)
      capped_total = cap_reading(total_byte_limit: 10_000_000_000, capped: true, capped_reason: CAPPED_REASON_TOTAL)
      not_capped = cap_reading
      [
        [false, false, CLIENT_LIMIT_STATUS_NONE, 0, nil, 0, "stopped"],
        [false, true, CLIENT_LIMIT_STATUS_NONE, 0, nil, 0, "signed out"],
        # client limit before paused
        [true, false, CLIENT_LIMIT_STATUS_EXCEEDED, TEST_RETRY_TIME, capped_monthly_zero, 3, "client limit, retry at 19:05 UTC"],
        [true, false, CLIENT_LIMIT_STATUS_NONE, 0, capped_monthly_zero, 3, "paused"],
        # the cap that capped_reason names decides paused
        [true, false, CLIENT_LIMIT_STATUS_NONE, 0, capped_total_zero, 3, "paused"],
        # paused before data cap reached
        [true, false, CLIENT_LIMIT_STATUS_NONE, 0, capped_monthly, 3, "data cap reached, resets 2026-11-01 00:00 UTC"],
        [true, false, CLIENT_LIMIT_STATUS_NONE, 0, capped_total, 0, "data cap reached"],
        [true, false, CLIENT_LIMIT_STATUS_NONE, 0, not_capped, 1, "connected"],
        [true, false, CLIENT_LIMIT_STATUS_NONE, 0, nil, 0, "connecting"],
      ].each do |started, signed_out, client_limit_status, retry_time, reading, providers_added, status|
        actual = Embed.embed_status(started, signed_out, client_limit_status, retry_time, reading, providers_added)
        expect(actual == status, "status #{actual.inspect}, want #{status.inspect} for started=#{started} signed_out=#{signed_out} reading=#{reading.inspect}")
      end
      # a monthly cap whose period end does not parse is reached without a reset time
      unparsed_end = cap_reading(monthly_byte_limit: 5, monthly_period_end: "soon", capped: true, capped_reason: CAPPED_REASON_MONTHLY)
      expect(Embed.embed_status(true, false, "", 0, unparsed_end, 1) == "data cap reached", "an unparsed period end must show plain data cap reached")
    end

    # checking, unavailable, a later failure keeping the last value, the
    # Embed-not-enabled refusal clearing it, no cap for an unset limit even
    # with a used count, and <used> of <limit>.
    def check_data_fields
      cap_state = CapState.new
      expect(Embed.data_field_text(cap_state, true) == "checking", "data this month before a reading must be checking")
      expect(Embed.data_field_text(cap_state, false) == "checking", "data total before a reading must be checking")
      cap_state.record(nil)
      expect(Embed.data_field_text(cap_state, true) == "unavailable", "a failed first reading must be unavailable")
      cap_state.record(nil)
      expect(Embed.data_field_text(cap_state, false) == "unavailable", "a second failure before any success stays unavailable")
      cap_state.record(cap_reading(monthly_byte_limit: 2000, monthly_used_byte_count: 1250, total_byte_limit: nil, total_used_byte_count: 999))
      expect(Embed.data_field_text(cap_state, true) == "1.2 kB of 2.0 kB", "a reading must show <used> of <limit>")
      expect(Embed.data_field_text(cap_state, false) == "no cap", "an unset cap shows no cap, never its used count")
      cap_state.record(nil)
      expect(Embed.data_field_text(cap_state, true) == "1.2 kB of 2.0 kB", "a later failure must keep the last value")
      cap_state.record(EMBED_NOT_ENABLED)
      expect(cap_state.reading.nil? && Embed.data_field_text(cap_state, true) == "unavailable" && Embed.data_field_text(cap_state, false) == "unavailable",
             "the Embed-not-enabled refusal must clear the last reading")
    end

    # Null or absent limits, capped and capped_reason, an unknown reason read
    # as capped without a reset time, and objects that are not cap objects.
    def check_cap_parsing
      minimal = Caps.parse_cap_object({"client_id" => TEST_CLIENT_ID})
      expect(!minimal.nil?, "a cap object with only client_id must parse")
      expect(minimal.monthly_byte_limit.nil? && minimal.total_byte_limit.nil?, "absent limits must be no cap")
      expect(minimal.monthly_used_byte_count.zero? && !minimal.capped && minimal.capped_reason == "", "absent counts and flags must default")
      nulls = Caps.parse_cap_object({"client_id" => TEST_CLIENT_ID, "monthly_byte_limit" => nil, "total_byte_limit" => 5, "capped" => nil})
      expect(!nulls.nil? && nulls.monthly_byte_limit.nil? && nulls.total_byte_limit == 5, "a null limit must be no cap")
      capped = Caps.parse_cap_answer(JSON.generate({
        "client_id" => TEST_CLIENT_ID, "monthly_byte_limit" => 10, "monthly_used_byte_count" => 10,
        "monthly_period_start" => "2026-10-01T00:00:00Z", "monthly_period_end" => "2026-11-01T00:00:00Z",
        "total_byte_limit" => nil, "total_used_byte_count" => 10, "total_period_start" => "2026-09-15T00:00:00Z",
        "capped" => true, "capped_reason" => "monthly",
      }))
      expect(!capped.nil? && capped.capped && capped.capped_reason == "monthly", "capped and capped_reason must parse")
      unknown = Caps.parse_cap_object({
        "client_id" => TEST_CLIENT_ID, "monthly_byte_limit" => 10, "monthly_period_end" => "2026-11-01T00:00:00Z",
        "capped" => true, "capped_reason" => "weekly",
      })
      expect(!unknown.nil?, "an unknown capped_reason must still parse")
      expect(Embed.embed_status(true, false, "", 0, unknown, 1) == "data cap reached", "an unknown capped_reason must read as capped without a reset time")
      [
        {"error" => {"message" => "no permission"}},
        {"client_id" => TEST_CLIENT_ID, "monthly_byte_limit" => "5"},
        {"client_id" => TEST_CLIENT_ID, "monthly_byte_limit" => -1},
        {"client_id" => TEST_CLIENT_ID, "monthly_byte_limit" => 5.0},
        {"client_id" => TEST_CLIENT_ID, "total_byte_limit" => true},
        {"client_id" => TEST_CLIENT_ID, "capped" => "yes"},
        {"client_id" => TEST_CLIENT_ID, "capped_reason" => 3},
        [TEST_CLIENT_ID],
        nil,
      ].each do |invalid|
        expect(Caps.parse_cap_object(invalid).nil? && !Caps.embed_not_enabled?(invalid), "#{invalid.inspect} must not parse as a cap object")
      end
      # the Embed-not-enabled refusal is no cap object, and is recognized
      refusal = {"error" => {"message" => "Embed isn't enabled for this network."}}
      expect(Caps.parse_cap_object(refusal).nil? && Caps.embed_not_enabled?(refusal), "the Embed-not-enabled refusal must be recognized")
      expect(Caps.read_own_caps(TEST_API, test_client_jwt, StandInServer.new([200, refusal])) == EMBED_NOT_ENABLED,
             "the cap read must mark the Embed-not-enabled refusal")
      expect(Caps.read_own_caps(TEST_API, test_client_jwt, StandInServer.new([200, {"error" => {"message" => "no permission"}}])).nil?,
             "another refusal must be a failed read")
      expect(Caps.parse_cap_answer("not json").nil?, "an answer that is not JSON must not parse")
      # the app's own read: a 404 from a server without the cap routes is a failure
      expect(Caps.read_own_caps(TEST_API, test_client_jwt, StandInServer.new([404, "not found"])).nil?, "a 404 must be a failed read")
      expect(Caps.read_own_caps(TEST_API, test_client_jwt, StandInServer.new(TransportError.new("unreachable"))).nil?, "an unreachable API must be a failed read")
      server = StandInServer.new([200, {"client_id" => TEST_CLIENT_ID, "monthly_byte_limit" => 7}])
      reading = Caps.read_own_caps(TEST_API, test_client_jwt, server)
      expect(!reading.nil? && reading.monthly_byte_limit == 7, "a cap answer must be read")
      request = server.requests[0]
      expect(request[:method] == "GET" && request[:url] == "#{TEST_API}/network/client-data-cap", "the cap read must GET /network/client-data-cap")
      expect(request[:headers]["Authorization"] == "Bearer #{test_client_jwt}", "the cap read must use the client JWT")
    end

    # The client limit status and the window status in the C ABI's JSON.
    def check_sdk_status_json
      expect(Embed.parse_client_limit_status(nil) == [CLIENT_LIMIT_STATUS_NONE, 0], "NULL must read as no client limit")
      expect(Embed.parse_client_limit_status(%({"Status":"client_limit_exceeded","RetryTime":#{TEST_RETRY_TIME}})) == [CLIENT_LIMIT_STATUS_EXCEEDED, TEST_RETRY_TIME],
             "the client limit status must parse")
      expect(Embed.parse_client_limit_status("not json") == [CLIENT_LIMIT_STATUS_NONE, 0], "invalid JSON must read as no client limit")
      expect(Embed.parse_providers_added(nil).zero?, "no window yet must be no providers")
      expect(Embed.parse_providers_added('{"ProviderStateAdded":2,"TargetSize":4}') == 2, "ProviderStateAdded must parse")
      expect(Embed.parse_providers_added('{"ProviderStateAdded":true}').zero?, "a non-integer ProviderStateAdded must be 0")
    end

    # A client JWT is accepted; a network JWT, a malformed token and an
    # invalid UUID are refused.
    def check_client_jwt_claims
      expect(State.parse_client_jwt_client_id(test_client_jwt) == TEST_CLIENT_ID, "a client JWT must be accepted")
      expect(State.parse_client_jwt_client_id(self_test_jwt(%({"client_id":"#{TEST_CLIENT_ID.upcase}"}))) == TEST_CLIENT_ID,
             "a client_id claim must be read in canonical form")
      [
        self_test_jwt('{"network_id":"44444444-4444-4444-4444-444444444444"}'),
        self_test_jwt('{"client_id":"not-a-uuid"}'),
        self_test_jwt('{"client_id":""}'),
        self_test_jwt('"a string"'),
        "not-a-jwt",
        "a.b",
        "a..c",
        "a.!!!.c",
      ].each do |client_jwt|
        expect_raises(ConfigError, "#{client_jwt.inspect} must be refused") { State.parse_client_jwt_client_id(client_jwt) }
      end
    end

    # The token server and API URLs are HTTPS origins, or explicit loopback HTTP.
    def check_origins
      [
        ["https://tokens.example.com", "https://tokens.example.com"],
        ["https://tokens.example.com/", "https://tokens.example.com"],
        ["https://tokens.example.com:8443", "https://tokens.example.com:8443"],
        ["http://127.0.0.1:8790", "http://127.0.0.1:8790"],
        ["http://localhost:8790", "http://localhost:8790"],
        ["http://[::1]:8790", "http://[::1]:8790"],
      ].each do |url, origin|
        actual = Transport.check_origin(url, "TEST")
        expect(actual == origin, "#{url.inspect} must be accepted as #{origin.inspect}, got #{actual.inspect}")
      end
      ["", "http://example.com", "https://example.com/path", "https://user:password@example.com", "https://example.com?query=1",
       "https://example.com?", "https://example.com#fragment", "ftp://example.com", "https://example.com:notaport"].each do |url|
        expect_raises(ConfigError, "#{url.inspect} must be refused") { Transport.check_origin(url, "TEST") }
      end
    end

    # The token fetch against a stand-in token server: the request, saving
    # client.jwt atomically, the client_id claim check, and the answers mapped
    # to the exit codes.
    def check_token_fetch
      private_dir do |state_dir|
        server = StandInServer.new([200, token_answer])
        fetched = ClientToken.fetch_client_jwt(state_dir, TEST_INSTANCE_ID, TEST_TOKEN_SERVER, TEST_SESSION, server)
        request = server.requests[0]
        expect(request[:method] == "POST", "the token fetch must POST")
        expect(request[:url] == TEST_TOKEN_SERVER + ClientToken::TOKEN_ROUTE, "the token fetch must post to /urnetwork/client-token")
        expect(request[:headers]["Authorization"] == "Bearer #{TEST_SESSION}", "the demo session must be the bearer token")
        expect(JSON.parse(request[:body]) == {"installation_id" => TEST_INSTANCE_ID}, "installation_id must equal the instance-id")
        expect(fetched.client_id == TEST_CLIENT_ID && fetched.client_jwt == test_client_jwt, "the answer must be returned")
        expect(!fetched.data_cap.nil? && fetched.data_cap.monthly_byte_limit == 10_000_000_000, "data_cap must be the first reading")
        client_jwt_path = File.join(state_dir, State::CLIENT_JWT_FILE_NAME)
        expect(State.read_private_file(client_jwt_path) == "#{test_client_jwt}\n", "client.jwt must hold the fetched token")
        expect((File.stat(client_jwt_path).mode & 0o777) == 0o600, "client.jwt must be 0600") if State::POSIX
        expect(Dir.children(state_dir).sort == [State::CLIENT_JWT_FILE_NAME], "the atomic write must leave no temporary file")

        # data_cap null, from a token server that could not read the caps
        fetched = ClientToken.fetch_client_jwt(state_dir, TEST_INSTANCE_ID, TEST_TOKEN_SERVER, TEST_SESSION, StandInServer.new([200, token_answer(data_cap: nil)]))
        expect(fetched.data_cap.nil?, "a null data_cap must leave no first reading")

        # a client_id that does not match the claim is refused, and client.jwt is kept
        mismatch = StandInServer.new([200, token_answer(client_id: TEST_OTHER_CLIENT_ID)])
        expect_raises(TokenServerError, "a client_id that does not match the claim must be refused") do
          ClientToken.fetch_client_jwt(state_dir, TEST_INSTANCE_ID, TEST_TOKEN_SERVER, TEST_SESSION, mismatch)
        end
        expect(State.read_private_file(client_jwt_path) == "#{test_client_jwt}\n", "a refused answer must not replace client.jwt")
        network_jwt = self_test_jwt('{"network_id":"44444444-4444-4444-4444-444444444444"}')
        [
          [[401, {"error" => {"code" => "unauthorized", "message" => "unknown session"}}], TokenServerRefused],
          [[409, {"error" => {"code" => "installation_limit", "message" => "too many installations"}}], TokenServerRefused],
          [[409, {"error" => {"code" => "client_limit", "message" => "client limit; see https://ur.io/services"}}], TokenServerRefused],
          [[503, {"error" => {"code" => "busy", "message" => "retry"}}], TokenServerError],
          [[502, {"error" => {"code" => "upstream", "message" => "upstream failed"}}], TokenServerError],
          [[500, "internal error"], TokenServerError],
          [[200, "not json"], TokenServerError],
          [[200, {"client_id" => TEST_CLIENT_ID}], TokenServerError],
          [[200, token_answer(client_jwt: network_jwt)], TokenServerError],
          [TransportError.new("connection refused"), TokenServerError],
        ].each do |answer, error_class|
          expect_raises(error_class, "the answer #{answer.inspect} must raise #{error_class}") do
            ClientToken.fetch_client_jwt(state_dir, TEST_INSTANCE_ID, TEST_TOKEN_SERVER, TEST_SESSION, StandInServer.new(answer))
          end
        end
        # the server's message is passed on
        begin
          ClientToken.fetch_client_jwt(state_dir, TEST_INSTANCE_ID, TEST_TOKEN_SERVER, TEST_SESSION,
                                       StandInServer.new([401, {"error" => {"code" => "unauthorized", "message" => "unknown session"}}]))
        rescue TokenServerRefused => error
          expect(error.message == "unknown session", "the token server's error message must be shown")
        end
      end

      # the run command maps the answers to the exit codes, and never prints the session
      [
        [[401, {"error" => {"code" => "unauthorized", "message" => "unknown session"}}], EXIT_CONFIG],
        [[409, {"error" => {"code" => "client_limit", "message" => "client limit"}}], EXIT_CONFIG],
        [[503, {"error" => {"code" => "busy", "message" => "retry"}}], EXIT_FAILURE],
        [TransportError.new("connection refused"), EXIT_FAILURE],
      ].each do |answer, exit_code|
        private_dir do |state_dir|
          settings = {"URNETWORK_EMBED_STATE_DIR" => state_dir, "URNETWORK_TOKEN_SERVER_URL" => TEST_TOKEN_SERVER, "URNETWORK_DEMO_SESSION" => TEST_SESSION}
          actual, output = embed_environment(settings) { captured { Embed.run(["run"], transport: StandInServer.new(answer)) } }
          expect(actual == exit_code, "the answer #{answer.inspect} must exit #{exit_code}, got #{actual}")
          expect(!output.include?(TEST_SESSION), "the demo session must never be printed")
        end
      end
    end

    # Private permissions on POSIX, atomic replacement, instance-id created
    # once and reused, and symlinked or oversized files refused.
    def check_state_files
      private_dir do |state_dir|
        State.check_state_dir(state_dir)
        path = File.join(state_dir, State::CLIENT_JWT_FILE_NAME)
        expect_raises(Errno::ENOENT, "a missing file must raise Errno::ENOENT") { State.read_private_file(path) }
        expect(State.load_client_jwt(state_dir).nil?, "a missing client.jwt must load as nil")
        State.write_private_file(path, "first\n")
        State.write_private_file(path, "  second  \n")
        expect(State.read_private_file(path) == "  second  \n", "the second write must replace the first")
        expect(State.load_client_jwt(state_dir) == "second", "client.jwt must load without surrounding whitespace")
        expect(Dir.children(state_dir).sort == [State::CLIENT_JWT_FILE_NAME], "the atomic writes must leave no temporary file")

        instance_id = State.load_or_create_instance_id(state_dir)
        expect(State.load_or_create_instance_id(state_dir) == instance_id, "instance-id must be created once and reused")
        State.write_private_file(File.join(state_dir, State::INSTANCE_ID_FILE_NAME), "not a uuid\n")
        expect_raises(ConfigError, "an invalid instance-id must be refused") { State.load_or_create_instance_id(state_dir) }

        large = File.join(state_dir, "large")
        State.write_private_file(large, "x" * (State::STATE_FILE_BYTE_LIMIT + 1))
        expect_raises(StateFileError, "an oversized state file must be refused") { State.read_private_file(large) }

        if State::POSIX
          State.write_private_file(path, "token\n")
          File.chmod(0o644, path)
          expect_raises(StateFileError, "a file readable by others must be refused") { State.read_private_file(path) }
          expect_raises(ConfigError, "an unprotected client.jwt must be a configuration error") { State.load_client_jwt(state_dir) }
          File.chmod(0o600, path)
          File.unlink(path)
          target = File.join(state_dir, "target")
          State.write_private_file(target, "token\n")
          File.symlink(target, path)
          expect_raises(StateFileError, "a symlinked state file must be refused") { State.read_private_file(path) }
          File.chmod(0o755, state_dir)
          expect_raises(ConfigError, "a state directory others can read must be refused") { State.check_state_dir(state_dir) }
          File.chmod(0o700, state_dir)
        end
      end
      expect_raises(ConfigError, "a missing state directory must be refused") { State.check_state_dir("") }
      expect_raises(ConfigError, "a relative state directory must be refused") { State.check_state_dir(File.join("relative", "state")) }
      private_dir do |parent|
        expect_raises(ConfigError, "a nonexistent state directory must be refused") { State.check_state_dir(File.join(parent, "missing")) }
      end
    end

    # The configuration errors exit with 78 before any SDK call, and so does a
    # usage error.
    def check_config_errors
      run_quietly = lambda do |args, settings = {}|
        embed_environment(settings) { captured { Embed.run(args, transport: StandInServer.new) }.first }
      end
      expect(run_quietly.call(["run"]) == EXIT_CONFIG, "a missing state directory must exit 78")
      expect(run_quietly.call(["run"], {"URNETWORK_EMBED_STATE_DIR" => File.join("relative", "state")}) == EXIT_CONFIG, "a relative state directory must exit 78")
      private_dir do |state_dir|
        expect(run_quietly.call([], {"URNETWORK_EMBED_STATE_DIR" => state_dir}) == EXIT_CONFIG, "no token server and no client.jwt must exit 78")
        expect(run_quietly.call(["run"], {"URNETWORK_EMBED_STATE_DIR" => state_dir, "URNETWORK_TOKEN_SERVER_URL" => TEST_TOKEN_SERVER}) == EXIT_CONFIG,
               "a token server URL without a demo session must exit 78")
        expect(run_quietly.call(["run"], {"URNETWORK_EMBED_STATE_DIR" => state_dir, "URNETWORK_TOKEN_SERVER_URL" => "http://example.com",
                                           "URNETWORK_DEMO_SESSION" => TEST_SESSION}) == EXIT_CONFIG,
               "a token server URL that is not HTTPS must exit 78")
        expect(run_quietly.call(["run"], {"URNETWORK_EMBED_STATE_DIR" => state_dir, "URNETWORK_API_URL" => "https://example.com/path"}) == EXIT_CONFIG,
               "an invalid API URL must exit 78")
        State.write_private_file(File.join(state_dir, State::CLIENT_JWT_FILE_NAME), "#{self_test_jwt('{"network_id":"44444444-4444-4444-4444-444444444444"}')}\n")
        expect(run_quietly.call(["run"], {"URNETWORK_EMBED_STATE_DIR" => state_dir}) == EXIT_CONFIG, "a network JWT in client.jwt must exit 78")
      end
      expect(run_quietly.call(["bogus"]) == EXIT_CONFIG, "an unknown command must exit 78")
      expect(run_quietly.call(%w[run extra]) == EXIT_CONFIG, "extra arguments must exit 78")
    end

    # The start line, the kind of app whose licenses --licenses prints, and
    # --licenses against a stand-in for the urnetwork module.
    def check_start_line
      expect(Embed.start_line(TEST_CLIENT_ID, TEST_INSTANCE_ID) == "embed client #{TEST_CLIENT_ID}, installation #{TEST_INSTANCE_ID}",
             "the start line must be the contract's")
      expect(%w[darwin25 mingw32 x64-mswin64 linux-gnu freebsd14].map { |host_os| Embed.license_app(host_os) } == %w[apple windows windows linux linux],
             "--licenses must ask for the platform's kind of app")
      expect(USAGE.include?("--licenses"), "the usage must name --licenses")

      licenses = nil
      raw = Module.new
      raw.define_singleton_method(:urnet_get_licenses) { |app| licenses&.call(app) }
      sdk = Module.new
      sdk.const_set(:Raw, raw)
      sdk.define_singleton_method(:take_string) { |text| text }
      licenses = ->(app) { JSON.generate([{"app" => app}]) }
      code, output = captured { Embed.print_licenses(sdk, "darwin25") }
      expect(code == EXIT_STOPPED && JSON.parse(output) == [{"app" => "apple"}], "--licenses must print the sdk's JSON for this kind of app")
      licenses = ->(_app) {}
      code, output = captured { Embed.print_licenses(sdk, "linux-gnu") }
      expect(code == EXIT_FAILURE && output.strip == "the sdk returned no licenses", "no licenses must exit 1")
    end
  end
end