envless-env 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3005e3dc4471d987d8960f6007d26aff6309c424a6f77cdfa5bc6150e7ea504c
+  data.tar.gz: 30efa0f02503e3524d6b84c7edadc3fa739998b1bb0bc68302bffa68b31c1eb9
+SHA512:
+  metadata.gz: 2e158c360a4c7e057ec90651a1fa7fb24263b486071f812f37f253f9779cb5654c6b5ff32a614c71d72307fc9f4f177668042f6397ae3c898d2ee5181aba2410
+  data.tar.gz: b961eaaecfc259e2272da9f458d87ccb9d8ff76010cbf728c9f51332a0f1da1d700c36492bc4f7c973541337e6657e7bfeeb2b2fceb2d7ed4b3c9df1a875e6b9

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.0.1
+
+The first release of the Ruby runtime, matching `@goenvless/env` as it stands in this repository. `rake parity` runs both packages through the same scenarios against one fake API and fails on any difference in the requests, the values, the types, the errors, the process environment, the warnings or the cache files.
+
+### Added
+
+`Envless::Env.load` fetches an environment's ciphertext with an `ev_sk_` machine key, decrypts it with `ENVLESS_KEY` or `ENVLESS_PASSPHRASE`, caches the ciphertext for 15 minutes in the files `@goenvless/env` uses, and fills `ENV` without overwriting anything already set or writing a name that changes how a process executes code, `RUBYOPT`, `RUBYLIB`, `BUNDLE_GEMFILE`, `GEM_HOME` and `GEM_PATH` included. Inside `envless run` it adopts the injected values with no credentials and no request. `require "envless/env/load"` loads at require.
+
+`Envless.env` reads every variable coerced to its type, `optional` reads `nil` for a missing name, and `client` sees only the client variables, with `snapshot` for templates. The views refuse to be dumped, marshalled or printed with their values. `Envless::Env.override` layers values for tests.
+
+`require "envless/env/rails"` adds a Railtie that loads before the app is configured and an `envless` view helper. `Envless::Env.fetch_environment` loads with explicit keywords for serverless functions, and the crypto helpers carry the encryption recipe. Every method has an RBS signature, and `bundle exec envless-env types` writes `sig/envless-env.rbs` from your variables, so Steep types every read by name.

data/README.md

@@ -0,0 +1,117 @@
+<div align='center'>
+   <a href='https://envless.cloud'>
+        <img
+            src='https://cdn-prod.envless.cloud/assets/npm/logo.svg'
+            alt='Envless Logo'
+            width='180'
+        />
+   </a>
+
+   <br />
+</div>
+
+<p align='center'>
+    End-to-end encrypted environment variables for teams. Load them into a Ruby app at boot, decrypted on your machine.
+</p>
+
+<p align='center'>
+    <a href='https://envless.cloud'>
+        <b>
+            Website
+        </b>
+    </a>
+    •
+    <a href='https://envless.cloud/dashboard'>
+        <b>
+            Dashboard
+        </b>
+    </a>
+    •
+    <a href='https://envless.cloud/docs/env-ruby/overview'>
+        <b>
+            Documentation
+        </b>
+    </a>
+    •
+    <a href='https://status.envless.cloud'>
+        <b>
+            Services Status
+        </b>
+    </a>
+</p>
+
+<br />
+
+## Intro to the Ruby runtime
+
+`envless-env` loads your Envless environment into a Ruby process when it starts. It fetches the ciphertext with a machine key, decrypts it in the process, fills `ENV` with every name that is safe to set, and gives your code `Envless.env`, which reads each variable coerced to the type you set in Envless. It is the Ruby twin of `@goenvless/env`: the same loader, the same on-disk cache and the same rules for the process environment.
+
+### Installing
+```bash
+bundle add envless-env
+```
+
+Or `gem install envless-env`. It needs Ruby 3.2 or newer and depends on `envless-sdk` only.
+
+### Loading
+```ruby
+require "envless/env/load"
+
+database_url = Envless.env[:DATABASE_URL]
+port = Envless.env[:PORT]
+```
+
+`envless/env/load` loads when it is required, so require it first. `require "envless/env"` loads nothing until you call `Envless::Env.load`, which returns a plain Hash of every value and is memoised, so later calls return the same values without fetching. `Envless::Env.load(revalidate: true)` fetches again.
+
+The loader reads `ENVLESS_TOKEN` (an `ev_sk_` machine key), `ENVLESS_KEY` or `ENVLESS_PASSPHRASE` to decrypt, and the product, project and environment from `ENVLESS_PRODUCT`, `ENVLESS_PROJECT` and `ENVLESS_ENV` or the `.envless` file `envless link` writes. The ciphertext is cached under `~/.envless/cache` for 15 minutes, in the same files `@goenvless/env` uses. Inside `envless run`, everything comes from the environment the CLI injected, with no credentials and no request.
+
+Values are written into `ENV` without overwriting anything already set, and names that change how a process executes code, such as `PATH`, `LD_PRELOAD`, `RUBYOPT` and `RUBYLIB`, are never written there at all.
+
+### Reading
+```ruby
+require "envless/env/load"
+
+port = Envless.env.fetch(:PORT, 3000)
+sentry_dsn = Envless.env.optional[:SENTRY_DSN]
+public_values = Envless.env.client.snapshot
+```
+
+A `number` reads back as an Integer, or a Float when it has a fraction, and a `boolean` as `true` or `false`. A missing name raises `Envless::Env::MissingVariableError` unless you read it through `optional`. The `client` view only sees the variables marked client in Envless. `Envless.env` never prints its values and refuses to be dumped or marshalled.
+
+### Types
+```bash
+bundle exec envless-env types
+```
+
+Writes `sig/envless-env.rbs` from your variable names, types and visibility, so Steep types `Envless.env.DATABASE_URL` as a `String` and catches a misspelt name or a server variable read through `client`. Under `envless run` it reads the injected manifest and needs no key.
+
+### Rails
+```ruby
+gem "envless-env", require: "envless/env/rails"
+```
+
+The Railtie loads before the app is configured, so `config/database.yml` and every initializer see the values, and views get an `envless` helper with the client variables.
+
+### Tests
+```ruby
+require "envless/env"
+
+Envless::Env.override(API_URL: "https://api.example.test") do
+  puts Envless.env[:API_URL]
+end
+```
+
+### Serverless
+```ruby
+require "envless/env"
+
+values = Envless::Env.fetch_environment(token: ENV.fetch("ENVLESS_TOKEN"),
+  project: "checkout-api", environment: "production",
+  key: ENV.fetch("ENVLESS_KEY"))
+
+puts values.size
+```
+
+`fetch_environment` takes every input as a keyword and touches nothing on disk or in `ENV`.
+
+Every load failure raises `Envless::Env::LoadError`, and every error inherits `Envless::Error` from `envless-sdk`. The gem ships RBS signatures: add `library "envless-sdk", "envless-env"` to your Steepfile.

data/exe/envless-env

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "envless/env/types"
+
+exit Envless::Env::Types::Command.call(ARGV)

data/lib/envless/env/api.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Envless
+  module Env
+    class Api
+      FAILURES = [Envless::Error, ArgumentError].freeze
+
+      def initialize(token, endpoint: nil, adapter: nil)
+        @client = Envless::Client.new(token:, base_url: endpoint, adapter:, user_agent: Settings::USER_AGENT,
+          disable_update_notice: true)
+      rescue *FAILURES => error
+        raise LoadError, error.message
+      end
+
+      def workspace_id
+        id = @client.workspace.get[:id]
+        id.is_a?(String) ? id : nil
+      rescue *FAILURES => error
+        raise LoadError, error.message
+      end
+
+      def variables(target)
+        listed = @client.variables.list_all(target.project, target.environment, product: target.product,
+          limit: Settings::PAGE_LIMIT)
+        listed.map do |variable|
+          {name: variable[:name], value: variable[:value] || "", type: variable[:type], visibility: variable[:visibility]}
+        end
+      end
+
+      def close
+        @client.close
+      end
+    end
+  end
+end

data/lib/envless/env/binding.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Envless
+  module Env
+    Binding = Data.define(:workspace, :product, :project, :environments)
+
+    class Binding
+      def self.read(directory = Dir.pwd)
+        parsed = Files.json(File.join(directory, Settings::ENVLESS_FILE))
+        return nil if parsed.nil?
+
+        workspace = parsed["workspace"]
+        project = parsed["project"]
+        environments = parsed["environments"]
+        return nil unless Files.text?(workspace) && Files.text?(project) && listed?(environments)
+
+        product = parsed["product"]
+        new(workspace:, product: Files.text?(product) ? product : nil, project:, environments:)
+      end
+
+      def self.listed?(environments)
+        environments.is_a?(Array) && !environments.empty? && environments.all? { |slug| Files.text?(slug) }
+      end
+    end
+  end
+end

data/lib/envless/env/cache.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Envless
+  module Env
+    module Cache
+      module_function
+
+      def path(target)
+        directory = Files.config_dir
+        return nil if directory.nil?
+
+        product = target.product ? sanitize(target.product) : Settings::CACHE_NO_PRODUCT
+        name = "#{product}__#{sanitize(target.project)}__#{sanitize(target.environment)}.json"
+        name = "#{sanitize(target.workspace)}__#{name}" if target.workspace
+        File.join(directory, Settings::CACHE_DIR, name)
+      end
+
+      def sanitize(slug)
+        Files.utf8(slug).gsub(Settings::CACHE_UNSAFE_CHARACTERS) { |character| (character.ord > 0xFFFF) ? "__" : "_" }
+      end
+
+      def read(target)
+        location = path(target)
+        parsed = location && Files.json(location)
+        return nil if parsed.nil? || !parsed["variables"].is_a?(Array)
+
+        variables = parsed["variables"].map { |entry| entry_of(entry) }
+        return nil if variables.any?(&:nil?)
+
+        workspace = parsed["workspace"].is_a?(String) ? parsed["workspace"] : nil
+        return nil unless workspace == target.workspace
+
+        {variables: variables.compact, cached_at: parsed["cachedAt"].is_a?(String) ? parsed["cachedAt"] : ""}
+      end
+
+      def entry_of(entry)
+        return nil unless entry.is_a?(Hash) && entry["name"].is_a?(String) && entry["value"].is_a?(String)
+
+        type = entry["type"]
+        visibility = entry["visibility"]
+        {name: entry["name"], value: entry["value"], type: type.is_a?(String) ? type : nil,
+         visibility: visibility.is_a?(String) ? visibility : nil}
+      end
+
+      def fresh?(cached_at, now = Time.now)
+        stamped = Time.iso8601(cached_at)
+        age = now - stamped
+        age >= 0 && age < Settings::CACHE_MAX_AGE
+      rescue ArgumentError
+        false
+      end
+    end
+  end
+end

data/lib/envless/env/cache_writer.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Envless
+  module Env
+    module CacheWriter
+      module_function
+
+      def write(target, variables, now = Time.now)
+        location = Cache.path(target)
+        return if location.nil?
+
+        directory = File.dirname(location)
+        FileUtils.mkdir_p(directory, mode: Settings::DIR_MODE)
+        File.chmod(Settings::DIR_MODE, File.dirname(directory))
+        File.chmod(Settings::DIR_MODE, directory)
+        replace(location, JSON.pretty_generate(payload(target, variables, now)))
+      end
+
+      def payload(target, variables, now)
+        entries = variables.map { |variable| variable.slice(:name, :value, :type, :visibility).compact }
+        written = {variables: entries, cachedAt: now.utc.iso8601(3)}
+        target.workspace ? written.merge(workspace: target.workspace) : written
+      end
+
+      def replace(location, content)
+        staged = "#{location}.tmp"
+        File.open(staged, File::WRONLY | File::CREAT | File::TRUNC, Settings::FILE_MODE) { |file| file.write(content) }
+        File.chmod(Settings::FILE_MODE, staged)
+        File.rename(staged, location)
+        File.chmod(Settings::FILE_MODE, location)
+      end
+    end
+  end
+end

data/lib/envless/env/coerce.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Envless
+  module Env
+    module Coerce
+      WHITESPACE = "\t\n\v\f\r    - 

  　"
+      DECIMAL = /\A[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?\z/
+      INFINITY = /\A([+-]?)Infinity\z/
+      RADIX = /\A0([xXoObB])([0-9a-fA-F]+)\z/
+      BASES = {"x" => 16, "o" => 8, "b" => 2}.freeze
+      TRUE_VALUES = %w[true 1].freeze
+
+      module_function
+
+      def call(value, type)
+        case type
+        when Settings::VAR_TYPES[:NUMBER] then number(value)
+        when Settings::VAR_TYPES[:BOOLEAN] then TRUE_VALUES.include?(value)
+        else value
+        end
+      end
+
+      def number(value)
+        text = trim(value)
+        return 0 if text.empty?
+
+        infinity = INFINITY.match(text)
+        return (infinity[1] == "-") ? -Float::INFINITY : Float::INFINITY if infinity
+
+        radix = RADIX.match(text)
+        return radix_number(radix[2], BASES.fetch(radix[1].downcase)) if radix
+        return Float::NAN unless DECIMAL.match?(text)
+
+        integral(text.sub(/\.(?!\d)/, ".0").to_f, text)
+      end
+
+      def trim(text)
+        text.gsub(/\A[#{WHITESPACE}]+|[#{WHITESPACE}]+\z/o, "")
+      end
+
+      def radix_number(digits, base)
+        Integer(digits, base, exception: false) || Float::NAN
+      end
+
+      def integral(parsed, text)
+        return parsed unless parsed.finite? && parsed == parsed.floor
+        return Integer(text.delete_prefix("+"), 10) if text.match?(/\A[+-]?\d+\z/)
+
+        parsed.to_i
+      end
+    end
+  end
+end

data/lib/envless/env/credentials.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Envless
+  module Env
+    module Credentials
+      module_function
+
+      def token
+        from_env = Files.variable(Settings::ENV_VARS[:TOKEN])
+        return from_env if Files.text?(from_env)
+
+        directory = Files.config_dir
+        stored = directory && Files.json(File.join(directory, Settings::CONFIG_FILE))
+        candidate = stored && stored["token"]
+        Files.text?(candidate) ? candidate : nil
+      end
+
+      def machine_token
+        resolved = token
+        raise LoadError, Messages::TOKEN_MISSING if resolved.nil?
+        raise LoadError, Messages::TOKEN_NOT_MACHINE unless resolved.start_with?(Settings::MACHINE_TOKEN_PREFIX)
+
+        resolved
+      end
+    end
+  end
+end

data/lib/envless/env/crypto.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Envless
+  module Env
+    module Crypto
+      def encrypt(plaintext, passphrase, workspace_unique_id)
+        Envless.encrypt_value(plaintext, passphrase, workspace_unique_id)
+      end
+
+      def decrypt(ciphertext, passphrase, workspace_unique_id)
+        Envless.decrypt_value(ciphertext, passphrase, workspace_unique_id)
+      end
+
+      def encrypt_with_key(key, plaintext)
+        Envless.encrypt_with_key(key, plaintext)
+      end
+
+      def decrypt_with_key(key, ciphertext)
+        Envless.decrypt_with_key(key, ciphertext)
+      end
+
+      def workspace_key(passphrase, workspace_unique_id)
+        Envless.derive_workspace_key(passphrase, workspace_unique_id)
+      end
+
+      def import_workspace_key(material)
+        Envless.import_workspace_key(material)
+      end
+
+      def passphrase_strength(passphrase)
+        Envless.passphrase_strength(passphrase)
+      end
+    end
+  end
+end

data/lib/envless/env/decryptor.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Envless
+  module Env
+    module Decryptor
+      Outcome = Data.define(:entries, :failed)
+      FAILURES = [Envless::Error, ArgumentError].freeze
+
+      module_function
+
+      def call(variables, keyring)
+        # @type var entries: Array[[String, String]]
+        entries = []
+        variables.each do |variable|
+          name = variable[:name]
+          value = variable[:value]
+          next unless value.is_a?(String)
+          next entries << [name, ""] if value.empty?
+
+          plaintext = attempt(keyring, value)
+          return Outcome.new(entries: nil, failed: name) if plaintext.nil?
+
+          entries << [name, plaintext]
+        end
+        Outcome.new(entries:, failed: nil)
+      end
+
+      def attempt(keyring, value)
+        keyring.decrypt(value)
+      rescue *FAILURES
+        nil
+      end
+    end
+  end
+end

data/lib/envless/env/environment_writer.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Envless
+  module Env
+    class EnvironmentWriter
+      def initialize
+        @owned = []
+      end
+
+      def write(record)
+        previous = @owned
+        previous.each { |name| ENV.delete(name) unless record.key?(name) }
+        # @type var refused: Array[String]
+        refused = []
+        # @type var unwritable: Array[String]
+        unwritable = []
+        # @type var owned: Array[String]
+        owned = []
+        record.each do |name, value|
+          next refused << name if Settings::UNSAFE_NAMES.include?(name.downcase)
+          next if ENV.key?(name) && !previous.include?(name)
+          next unwritable << name unless writable?(name, value)
+
+          ENV[name] = value
+          owned << name
+        end
+        @owned = owned
+        report(refused, unwritable)
+      end
+
+      private
+
+      def writable?(name, value)
+        !name.empty? && !name.include?("=") && !name.include?("\0") && !value.include?("\0")
+      end
+
+      def report(refused, unwritable)
+        warn format(Messages::UNSAFE_REFUSED, names: refused.join(", ")) unless refused.empty?
+        warn format(Messages::UNWRITABLE, names: unwritable.join(", ")) unless unwritable.empty?
+      end
+    end
+  end
+end

data/lib/envless/env/errors.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Envless
+  module Env
+    class Error < Envless::Error
+    end
+
+    class LoadError < Error
+    end
+
+    class NotLoadedError < Error
+    end
+
+    class VariableError < Error
+      attr_reader :variable
+
+      def initialize(variable, template)
+        @variable = variable
+        super(format(template, name: variable))
+      end
+    end
+
+    class MissingVariableError < VariableError
+      def initialize(variable)
+        super(variable, Messages::MISSING_VARIABLE)
+      end
+    end
+
+    class ServerOnlyError < VariableError
+      def initialize(variable)
+        super(variable, Messages::SERVER_ONLY)
+      end
+    end
+
+    class ReadOnlyError < Error
+      def initialize(message = Messages::READ_ONLY)
+        super
+      end
+    end
+
+    class SerialisationError < Error
+      def initialize(message = Messages::NOT_SERIALISABLE)
+        super
+      end
+    end
+  end
+end

data/lib/envless/env/files.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Envless
+  module Env
+    module Files
+      module_function
+
+      def json(path)
+        return nil unless File.file?(path)
+
+        parsed = JSON.parse(File.read(path, encoding: Encoding::UTF_8))
+        parsed.is_a?(Hash) ? parsed : nil
+      rescue JSON::ParserError, SystemCallError, IOError, EncodingError
+        nil
+      end
+
+      def home
+        Dir.home
+      rescue ArgumentError
+        nil
+      end
+
+      def config_dir
+        root = home
+        root && File.join(root, Settings::CONFIG_DIR)
+      end
+
+      def text?(value)
+        value.is_a?(String) && !value.empty?
+      end
+
+      def variable(name)
+        value = ENV.fetch(name, nil)
+        value && utf8(value)
+      end
+
+      def utf8(text)
+        return text if text.encoding == Encoding::UTF_8 && text.valid_encoding?
+
+        text.dup.force_encoding(Encoding::UTF_8).scrub
+      end
+    end
+  end
+end

data/lib/envless/env/injected.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Envless
+  module Env
+    module Injected
+      TYPES = Settings::VAR_TYPES.values.freeze
+      VISIBILITIES = Settings::VISIBILITY.values.freeze
+
+      module_function
+
+      def seed
+        raw = Files.variable(Settings::INJECTED[:NAME])
+        return nil if raw.nil? || raw.empty?
+
+        manifest = parse(raw)
+        return nil unless manifest.is_a?(Hash)
+
+        # @type var record: Hash[String, String]
+        record = {}
+        # @type var meta: Hash[String, meta]
+        meta = {}
+        manifest.each do |name, entry|
+          next unless name.is_a?(String)
+
+          value = Files.variable(name)
+          next if value.nil? || Settings::UNSAFE_NAMES.include?(name.downcase)
+
+          record[name] = value
+          meta[name] = meta_of(entry)
+        end
+        record.empty? ? nil : [record, meta]
+      end
+
+      def parse(raw)
+        JSON.parse(raw)
+      rescue JSON::ParserError, EncodingError
+        nil
+      end
+
+      def meta_of(entry)
+        return {type: Settings::DEFAULT_TYPE, visibility: Settings::DEFAULT_VISIBILITY} unless entry.is_a?(Hash)
+
+        type = entry[Settings::INJECTED[:TYPE_KEY]]
+        visibility = entry[Settings::INJECTED[:VISIBILITY_KEY]]
+        {type: TYPES.include?(type) ? type : Settings::DEFAULT_TYPE,
+         visibility: VISIBILITIES.include?(visibility) ? visibility : Settings::DEFAULT_VISIBILITY}
+      end
+    end
+  end
+end

data/lib/envless/env/isolated.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Envless
+  module Env
+    module Isolated
+      module_function
+
+      def call(token:, project:, environment:, product: nil, passphrase: nil, key: nil, workspace_id: nil, endpoint: nil,
+        adapter: nil)
+        raise LoadError, Messages::ISOLATED_NO_TOKEN unless Files.text?(token)
+        raise LoadError, Messages::ISOLATED_NO_TARGET unless Files.text?(project) && Files.text?(environment)
+        raise LoadError, Messages::ISOLATED_NO_KEY_MATERIAL unless Files.text?(passphrase) || Files.text?(key)
+
+        api = Api.new(token, endpoint:, adapter:)
+        begin
+          decrypted(api, keyring_of(api, passphrase, key, workspace_id), product, project, environment)
+        ensure
+          api.close
+        end
+      rescue Envless::Error, ArgumentError => error
+        raise error if error.is_a?(LoadError)
+
+        raise LoadError, error.message
+      end
+
+      def decrypted(api, keyring, product, project, environment)
+        target = Target.new(workspace: nil, product: Files.text?(product) ? product : nil, project:, environment:)
+        outcome = Decryptor.call(api.variables(target), keyring)
+        entries = outcome.entries
+        raise LoadError, format(Messages::ISOLATED_DECRYPT_FAILED, name: outcome.failed) if entries.nil?
+
+        entries.to_h
+      end
+
+      def keyring_of(api, passphrase, key, workspace_id)
+        return Keyring.imported(key) if key && !key.empty?
+
+        workspace = (workspace_id && !workspace_id.empty?) ? workspace_id : api.workspace_id
+        raise LoadError, Messages::ISOLATED_NO_WORKSPACE if workspace.nil? || workspace.empty?
+
+        Keyring.derived(passphrase.to_s, workspace)
+      end
+    end
+  end
+end