Developer SDK

Ruby examples

Install the SDK · View source on GitHub ↗

provider/state.rb

ruby
# frozen_string_literal: true

# Installation state for one provider install, kept in one private directory
# named by URNETWORK_PROVIDER_STATE_DIR (PROVIDER_CONTRACT.md, "Installation
# state"):
#
# - client.jwt: the scoped client credential that the developer's backend
#   issued for this installation. The developer writes it; the app rewrites it
#   whenever the SDK refreshes the token.
# - instance-id: this installation's UUID, created on first run.
# - identity.json: the provider identity (client key seed, provide TLS
#   certificate and key, extender seed), created on first run so the provider
#   keeps one identity across restarts.
#
# Every file is replaced atomically with owner-only permissions, and a
# symlinked file is refused. On POSIX the directory and its files must not be
# accessible to group or others; Windows relies on the access control of the
# user's profile directory. Plain Ruby: the self-test runs it without the
# native SDK.

require "json"
require "securerandom"
require_relative "status"

module Provider
  # A configuration or credential problem that restarting does not fix (exit 78).
  class ConfigError < StandardError; end

  # A state file that the app must not read: not a regular file, too large or
  # accessible to others.
  class StateFileError < StandardError; end

  # identity.json. Byte fields are binary strings here and standard base64 in
  # JSON. An identity belongs to one client: a newly provisioned client gets a
  # new identity.
  Identity = Struct.new(
    :client_id,
    :client_key_seed,
    :provide_tls_certificate_pem,
    :provide_tls_private_key_pem,
    :extender_key_seed,
    keyword_init: true,
  )

  # The byte fields of the SDK's device key material: the client key seed, the
  # provide TLS certificate and key in the order
  # urnet_new_device_local_key_material takes them, and the extender seed for
  # urnet_device_local_key_material_set_extender_key_seed.
  KeyMaterial = Struct.new(
    :client_key_seed,
    :provide_tls_certificate_pem,
    :provide_tls_private_key_pem,
    :extender_key_seed,
    keyword_init: true,
  )

  # The installation state loaded at start. client_id is the client_id claim
  # of client_jwt; identity is nil on first run, and when the stored identity
  # belongs to another client.
  Config = Struct.new(:state_dir, :client_jwt, :client_id, :instance_id, :identity, keyword_init: true)

  # Reads and writes the installation state directory.
  module State
    CLIENT_JWT_FILE_NAME = "client.jwt"
    INSTANCE_ID_FILE_NAME = "instance-id"
    IDENTITY_FILE_NAME = "identity.json"

    # the largest state file the app reads
    STATE_FILE_BYTE_LIMIT = 64 * 1024

    PROVIDER_IDENTITY_VERSION = 1

    # a uuid in its canonical 8-4-4-4-12 form, or as 32 hex digits
    UUID_PATTERN = /\A(?:\h{8}-\h{4}-\h{4}-\h{4}-\h{12}|\h{32})\z/.freeze

    # unpadded base64url, the encoding of a JWT segment
    BASE64URL_PATTERN = /\A[A-Za-z0-9_-]*\z/.freeze

    POSIX = !Gem.win_platform?

    module_function

    # Loads the installation state, creating instance-id on first run. Every
    # error is a ConfigError: restarting does not fix it.
    def load_config(state_dir)
      check_state_dir(state_dir)
      begin
        client_jwt_bytes = read_private_file(File.join(state_dir, CLIENT_JWT_FILE_NAME))
      rescue SystemCallError, StateFileError => error
        raise ConfigError, "read #{CLIENT_JWT_FILE_NAME} from the state directory: #{error.message}"
      end
      client_jwt = text(client_jwt_bytes).strip
      client_id = parse_client_jwt_client_id(client_jwt)
      Config.new(
        state_dir: state_dir,
        client_jwt: client_jwt,
        client_id: client_id,
        instance_id: load_or_create_instance_id(state_dir),
        identity: load_identity(state_dir, client_id),
      )
    end

    # The state directory must be an existing absolute directory, private to
    # its owner on POSIX.
    def check_state_dir(state_dir)
      if state_dir.nil? || state_dir.empty?
        raise ConfigError, "set URNETWORK_PROVIDER_STATE_DIR to this installation's private state directory"
      end
      raise ConfigError, "URNETWORK_PROVIDER_STATE_DIR must be an absolute path" unless File.absolute_path?(state_dir)

      begin
        info = File.stat(state_dir)
      rescue SystemCallError => error
        raise ConfigError, "state directory: #{error.message}"
      end
      raise ConfigError, "URNETWORK_PROVIDER_STATE_DIR is not a directory" unless info.directory?
      raise ConfigError, "the state directory must be private to its owner (chmod 700)" if POSIX && (info.mode & 0o077) != 0
    end

    # Reads a regular, private state file of bounded size, as a binary string.
    # A symlink is refused so that the credential cannot be redirected to
    # another file. Raises Errno::ENOENT when the file does not exist.
    def read_private_file(path)
      info = File.lstat(path)
      raise StateFileError, "not a regular file" unless info.file?
      raise StateFileError, "file is too large" if STATE_FILE_BYTE_LIMIT < info.size
      raise StateFileError, "file must be private to its owner (chmod 600)" if POSIX && (info.mode & 0o077) != 0

      flags = File::RDONLY | File::BINARY
      # no-follow closes the window between the check and the open where POSIX has it
      flags |= File::NOFOLLOW if defined?(File::NOFOLLOW)
      data = File.open(path, flags) { |file| file.read(STATE_FILE_BYTE_LIMIT + 1) } || "".b
      raise StateFileError, "file is too large" if STATE_FILE_BYTE_LIMIT < data.bytesize

      data
    end

    # Replaces a state file atomically: a private temporary file in the same
    # directory is written, synced and renamed over the old file.
    def write_private_file(path, data)
      temp_path = File.join(File.dirname(path), ".#{File.basename(path)}.#{SecureRandom.hex(8)}")
      file = File.open(temp_path, File::WRONLY | File::CREAT | File::EXCL | File::BINARY, 0o600)
      begin
        # the umask can only narrow 0o600; this keeps it exact
        file.chmod(0o600) if POSIX
        file.write(data)
        file.flush
        file.fsync
        file.close
        File.rename(temp_path, path)
      rescue StandardError
        file.close unless file.closed?
        begin
          File.unlink(temp_path)
        rescue SystemCallError
          nil
        end
        raise
      end
    end

    # The UTF-8 text of file bytes, with invalid bytes replaced.
    def text(data)
      data.dup.force_encoding(Encoding::UTF_8).scrub
    end

    # The canonical lowercase form of a UUID, or nil when value is not one.
    def parse_uuid(value)
      return nil unless value.is_a?(String) && UUID_PATTERN.match?(value)

      hex = value.delete("-").downcase
      "#{hex[0, 8]}-#{hex[8, 4]}-#{hex[12, 4]}-#{hex[16, 4]}-#{hex[20, 12]}"
    end

    # The client_id claim of a scoped client JWT. This checks the token's shape
    # and claim only; the SDK and the server verify the token itself.
    def parse_client_jwt_client_id(client_jwt)
      not_jwt = "client.jwt does not hold a JWT; write the scoped client JWT from your backend"
      parts = client_jwt.split(".", -1)
      raise ConfigError, not_jwt unless parts.length == 3 && parts.none?(&:empty?)

      payload_text = parts[1].sub(/=+\z/, "")
      raise ConfigError, not_jwt unless BASE64URL_PATTERN.match?(payload_text) && payload_text.length % 4 != 1

      begin
        payload = (payload_text.tr("-_", "+/") + ("=" * (-payload_text.length % 4))).unpack1("m0")
      rescue ArgumentError
        raise ConfigError, not_jwt
      end
      claims = Provider.parse_json_object(payload)
      client_id_claim = claims && claims["client_id"]
      unless client_id_claim.is_a?(String) && !client_id_claim.empty?
        raise ConfigError, "client.jwt has no client_id claim; write a scoped client JWT, not a network JWT"
      end

      client_id = parse_uuid(client_id_claim)
      raise ConfigError, "client.jwt has an invalid client_id claim" if client_id.nil?

      client_id
    end

    # Reads instance-id, creating it on first run. An installation keeps one
    # instance id for its lifetime.
    def load_or_create_instance_id(state_dir)
      path = File.join(state_dir, INSTANCE_ID_FILE_NAME)
      begin
        data = read_private_file(path)
      rescue Errno::ENOENT
        data = nil
      rescue SystemCallError, StateFileError => error
        raise ConfigError, "read #{INSTANCE_ID_FILE_NAME} from the state directory: #{error.message}"
      end
      unless data.nil?
        instance_id = parse_uuid(text(data).strip)
        raise ConfigError, "#{INSTANCE_ID_FILE_NAME} does not hold a UUID" if instance_id.nil?

        return instance_id
      end
      instance_id = SecureRandom.uuid
      begin
        write_private_file(path, "#{instance_id}\n")
      rescue SystemCallError => error
        raise ConfigError, "write #{INSTANCE_ID_FILE_NAME}: #{error.message}"
      end
      instance_id
    end

    # Reads identity.json for client_id. A missing file, or an identity of
    # another client, returns nil: the device then creates a new identity,
    # which the app saves.
    def load_identity(state_dir, client_id)
      begin
        data = read_private_file(File.join(state_dir, IDENTITY_FILE_NAME))
      rescue Errno::ENOENT
        return nil
      rescue SystemCallError, StateFileError => error
        raise ConfigError, "read #{IDENTITY_FILE_NAME} from the state directory: #{error.message}"
      end
      identity = parse_identity(data)
      if identity.nil?
        raise ConfigError, "#{IDENTITY_FILE_NAME} is not a valid provider identity; remove it to create a new one"
      end
      return nil if identity.client_id != client_id

      identity
    end

    # The identity in identity.json, or nil when the file does not parse, has
    # another version or a client key seed that is not 32 bytes.
    def parse_identity(data)
      decode_bytes = lambda do |value|
        # json null and a missing field are empty, as in the go reference
        next "".b if value.nil?
        next nil unless value.is_a?(String)

        begin
          value.unpack1("m0")
        rescue ArgumentError
          nil
        end
      end
      fields = Provider.parse_json_object(data)
      return nil if fields.nil?
      return nil unless fields["version"].is_a?(Integer) && fields["version"] == PROVIDER_IDENTITY_VERSION

      # a null client id names no client, as in the go reference
      client_id = fields["client_id"] || ""
      return nil unless client_id.is_a?(String)

      byte_fields = %w[client_key_seed provide_tls_certificate_pem provide_tls_private_key_pem extender_key_seed].map do |name|
        decode_bytes.call(fields[name])
      end
      return nil if byte_fields.any?(&:nil?) || byte_fields[0].bytesize != 32

      Identity.new(
        client_id: client_id,
        client_key_seed: byte_fields[0],
        provide_tls_certificate_pem: byte_fields[1],
        provide_tls_private_key_pem: byte_fields[2],
        extender_key_seed: byte_fields[3],
      )
    end

    # Writes identity.json.
    def save_identity(state_dir, identity)
      encode_bytes = ->(value) { [value].pack("m0") }
      fields = {
        "version" => PROVIDER_IDENTITY_VERSION,
        "client_id" => identity.client_id,
        "client_key_seed" => encode_bytes.call(identity.client_key_seed),
        "provide_tls_certificate_pem" => encode_bytes.call(identity.provide_tls_certificate_pem),
        "provide_tls_private_key_pem" => encode_bytes.call(identity.provide_tls_private_key_pem),
      }
      unless identity.extender_key_seed.nil? || identity.extender_key_seed.empty?
        fields["extender_key_seed"] = encode_bytes.call(identity.extender_key_seed)
      end
      write_private_file(File.join(state_dir, IDENTITY_FILE_NAME), JSON.generate(fields))
    end

    # The key material that recreates the device's identity. nil without an
    # identity (the first run, or another client's identity): the device then
    # makes a new identity, which the app saves.
    def key_material(identity)
      return nil if identity.nil?

      KeyMaterial.new(
        client_key_seed: identity.client_key_seed,
        provide_tls_certificate_pem: identity.provide_tls_certificate_pem,
        provide_tls_private_key_pem: identity.provide_tls_private_key_pem,
        extender_key_seed: identity.extender_key_seed || "".b,
      )
    end
  end
end