Developer SDK

Ruby examples

Install the SDK · View source on GitHub ↗

embed/state.rb

ruby
# frozen_string_literal: true

# Installation state for one embed installation, kept in one private directory
# named by URNETWORK_EMBED_STATE_DIR (EMBED_CONTRACT.md, "Installation state"):
#
# - client.jwt: the scoped client JWT. With a token server configured the app
#   fetches and writes it at every start; otherwise a backend tool's
#   `provision` or the developer writes it. The app rewrites it whenever the
#   SDK refreshes the token. It is a bearer secret: never printed or logged.
# - instance-id: this installation's UUID, created on first run and kept for
#   the life of the installation. It is also the installation ID that the app
#   sends to the token server.
# - logs/: the SDK's bounded log files.
#
# 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 (keep the directory under %LOCALAPPDATA%). Plain
# Ruby: the self-test runs it without the native SDK.

require "json"
require "securerandom"

module Embed
  # 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

  # A JSON object from text (the C ABI's strings, an answer body), or nil for
  # nil, JSON null or anything that is not an object.
  def self.parse_json_object(text)
    return nil if text.nil? || text.empty?

    value = JSON.parse(text)
    value.is_a?(Hash) ? value : nil
  rescue JSON::ParserError, EncodingError
    nil
  end

  # Reads and writes the installation state directory.
  module State
    STATE_DIR_SETTING = "URNETWORK_EMBED_STATE_DIR"

    CLIENT_JWT_FILE_NAME = "client.jwt"
    INSTANCE_ID_FILE_NAME = "instance-id"
    LOG_DIR_NAME = "logs"

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

    # 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

    # 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 #{STATE_DIR_SETTING} to this installation's private state directory"
      end
      raise ConfigError, "#{STATE_DIR_SETTING} 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, "#{STATE_DIR_SETTING} 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, in canonical form. This
    # checks the token's shape and claim only; the SDK and the server verify
    # the token itself. A network JWT has no client_id claim and is refused.
    def parse_client_jwt_client_id(client_jwt)
      not_jwt = "client.jwt does not hold a JWT; fetch one from your token server or 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 = Embed.parse_json_object(text(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; use 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; it is also its installation ID.
    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

    # The client JWT in client.jwt with surrounding whitespace removed, or nil
    # when the file does not exist.
    def load_client_jwt(state_dir)
      text(read_private_file(File.join(state_dir, CLIENT_JWT_FILE_NAME))).strip
    rescue Errno::ENOENT
      nil
    rescue SystemCallError, StateFileError => error
      raise ConfigError, "read #{CLIENT_JWT_FILE_NAME} from the state directory: #{error.message}"
    end

    # Writes client.jwt atomically. Raises SystemCallError.
    def save_client_jwt(state_dir, client_jwt)
      write_private_file(File.join(state_dir, CLIENT_JWT_FILE_NAME), "#{client_jwt}\n")
    end
  end
end