envless-env 0.0.1

data/lib/envless/env/keyring.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Envless
+  module Env
+    class Keyring
+      PINNED = /\Av2:(\d+):/
+      DEFAULT_ITERATIONS = Envless::ENCRYPTION_PARAMETERS[:pbkdf2Iterations]
+
+      def self.from_environment(api)
+        raw = Files.variable(Settings::ENV_VARS[:KEY])
+        return imported(raw) if raw && !raw.empty?
+
+        passphrase = Files.variable(Settings::ENV_VARS[:PASSPHRASE])
+        raise LoadError, Messages::KEY_MATERIAL_MISSING if passphrase.nil? || passphrase.empty?
+
+        derived(passphrase, api.workspace_id)
+      end
+
+      def self.imported(raw)
+        new(Envless.import_workspace_key(raw))
+      rescue ArgumentError => error
+        raise LoadError, format(Messages::KEY_INVALID, reason: error.message)
+      end
+
+      def self.derived(passphrase, workspace_id)
+        raise LoadError, Messages::WORKSPACE_UNRESOLVED if workspace_id.nil? || workspace_id.empty?
+
+        new(Envless.derive_workspace_key(passphrase, workspace_id), passphrase:, workspace_id:)
+      end
+
+      def initialize(key, passphrase: nil, workspace_id: nil)
+        @key = key
+        @passphrase = passphrase
+        @workspace_id = workspace_id
+        freeze
+      end
+
+      def decrypt(value)
+        pinned = PINNED.match(value)
+        passphrase = @passphrase
+        workspace_id = @workspace_id
+        if pinned && passphrase && workspace_id && Integer(pinned[1], 10) != DEFAULT_ITERATIONS
+          return Envless.decrypt_value(value, passphrase, workspace_id)
+        end
+
+        Envless.decrypt_with_key(@key, value)
+      end
+
+      def inspect
+        "#<#{self.class.name} [redacted]>"
+      end
+    end
+  end
+end

data/lib/envless/env/load.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "../env"
+
+Envless::Env.load

data/lib/envless/env/loader.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Envless
+  module Env
+    class Loader
+      def initialize(store, writer)
+        @store = store
+        @writer = writer
+        @lock = Mutex.new
+        @memo = nil
+      end
+
+      def load(revalidate: false)
+        UpdateNotice.check
+        return @store.snapshot if @store.injected? && !revalidate
+
+        @lock.synchronize do
+          memo = @memo
+          if memo.nil? || revalidate
+            memo = fresh(revalidate)
+            @memo = memo
+          end
+          memo.dup
+        end
+      end
+
+      private
+
+      def fresh(revalidate)
+        token = Credentials.machine_token
+        target = Target.resolve
+        api = Api.new(token)
+        begin
+          keyring = Keyring.from_environment(api)
+          cached = revalidate ? nil : from_cache(target, keyring)
+          cached || fetched(api, target, keyring)
+        ensure
+          api.close
+        end
+      end
+
+      def from_cache(target, keyring)
+        cached = Cache.read(target)
+        return nil if cached.nil? || !Cache.fresh?(cached[:cached_at])
+
+        outcome = Decryptor.call(cached[:variables], keyring)
+        outcome.entries && finish(outcome.entries, cached[:variables])
+      end
+
+      def fetched(api, target, keyring)
+        variables = fetch(api, target)
+        begin
+          CacheWriter.write(target, variables)
+        rescue SystemCallError, IOError
+          nil
+        end
+        outcome = Decryptor.call(variables, keyring)
+        raise LoadError, format(Messages::DECRYPT_FAILED, name: outcome.failed) if outcome.entries.nil?
+
+        finish(outcome.entries, variables)
+      end
+
+      def fetch(api, target)
+        api.variables(target)
+      rescue Envless::Error, ArgumentError => error
+        raise LoadError, format(Messages::FETCH_FAILED, project: target.project, environment: target.environment,
+          reason: error.message)
+      end
+
+      def finish(entries, sources)
+        record = entries.to_h
+        # @type var meta: Hash[String, meta]
+        meta = sources.to_h do |source|
+          [source[:name], {type: source[:type] || Settings::DEFAULT_TYPE,
+                           visibility: source[:visibility] || Settings::DEFAULT_VISIBILITY}]
+        end
+        @store.replace(record, meta)
+        @writer.write(record)
+        record
+      end
+    end
+  end
+end

data/lib/envless/env/messages.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Envless
+  module Env
+    module Messages
+      TOKEN_MISSING = "Missing ENVLESS_TOKEN. Set it to an Envless machine key (ev_sk_…) to load variables."
+      TOKEN_NOT_MACHINE = "ENVLESS_TOKEN must be a machine key (ev_sk_…). Create one in the Envless dashboard."
+      PROJECT_MISSING = "Missing ENVLESS_PROJECT. Set it to your project slug, or add a .envless file."
+      ENVIRONMENT_MISSING = "Missing ENVLESS_ENV. Set it to your environment slug, or add a .envless file."
+      KEY_MATERIAL_MISSING = "Set ENVLESS_KEY (a workspace key) or ENVLESS_PASSPHRASE to decrypt in machine mode."
+      KEY_INVALID = "ENVLESS_KEY is invalid: %<reason>s"
+      WORKSPACE_UNRESOLVED = "ENVLESS_PASSPHRASE is set but the workspace could not be resolved to derive the key."
+      FETCH_FAILED = "Could not load variables for %<project>s/%<environment>s: %<reason>s"
+      DECRYPT_FAILED = "Could not decrypt %<name>s. Check ENVLESS_KEY or ENVLESS_PASSPHRASE."
+      NOT_LOADED = "Envless env is not loaded yet. Call Envless::Env.load, or require \"envless/env/load\", first."
+      MISSING_VARIABLE = "Missing env var: %<name>s"
+      READ_ONLY = "Envless env is read-only."
+      SERVER_ONLY = "%<name>s is server only. Read it through Envless.env, not Envless.env.client."
+      NOT_SERIALISABLE = "Refusing to serialise the Envless env, because it holds decrypted secrets and this would copy " \
+        "every one of them into the output. Read the names you need, or call Envless::Env.load for a plain Hash you own."
+      UNSAFE_REFUSED = "#{Settings::LOG_PREFIX} These variables were decrypted but not written into the process " \
+        "environment, because their names change how this process or its children execute code, so storing one turns " \
+        "write access to a variable into code execution: %<names>s"
+      UNWRITABLE = "#{Settings::LOG_PREFIX} These variables were decrypted but not written into the process environment, " \
+        "because the operating system cannot hold their name or value in one: %<names>s"
+      ISOLATED_NO_TOKEN = "Pass a machine key as token:. A side-effect-free load reads no .envless file and no config."
+      ISOLATED_NO_TARGET = "Pass project: and environment:. A side-effect-free load has no .envless file to resolve them from."
+      ISOLATED_NO_KEY_MATERIAL = "Pass passphrase: or key:. Without one the values cannot be decrypted."
+      ISOLATED_NO_WORKSPACE = "The workspace could not be resolved, so the passphrase cannot be turned into a key. " \
+        "Pass workspace_id: explicitly."
+      ISOLATED_DECRYPT_FAILED = "Could not decrypt %<name>s"
+      UPDATE_AVAILABLE = "ℹ envless-env %<latest>s is available, you are on %<current>s. Upgrade with " \
+        "bundle update envless-env. %<changelog>s."
+    end
+  end
+end

data/lib/envless/env/override.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Envless
+  module Env
+    class Override
+      def initialize(store, layer)
+        @store = store
+        @layer = layer
+        freeze
+      end
+
+      def restore
+        @store.pop(@layer)
+      end
+    end
+  end
+end

data/lib/envless/env/rails.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "../env"
+
+module Envless
+  module Env
+    module ViewHelper
+      def envless
+        Envless.env.client.snapshot
+      end
+    end
+
+    class Railtie < ::Rails::Railtie
+      config.before_configuration { Envless::Env.load }
+
+      initializer "envless.view_helper" do
+        ActiveSupport.on_load(:action_view) { include Envless::Env::ViewHelper }
+      end
+    end
+  end
+end

data/lib/envless/env/serialisation.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Envless
+  module Env
+    module Serialisation
+      def to_h
+        raise SerialisationError unless client?
+
+        keys.to_h { |name| [name, self[name]] }
+      end
+
+      def snapshot
+        to_h
+      end
+
+      def as_json(*)
+        to_h
+      end
+
+      def to_json(*)
+        to_h.to_json(*)
+      end
+
+      def marshal_dump
+        raise SerialisationError
+      end
+
+      def encode_with(_coder)
+        raise SerialisationError
+      end
+
+      def dup
+        self
+      end
+
+      def clone(freeze: nil)
+        self
+      end
+
+      def inspect
+        count = keys.size
+        "#<#{self.class.name}#{" client" if client?}#{" optional" if optional?} #{count} variable#{"s" unless count == 1}>"
+      end
+
+      def to_s
+        inspect
+      end
+    end
+  end
+end

data/lib/envless/env/settings.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Envless
+  module Env
+    module Settings
+      ENV_VARS = {
+        TOKEN: "ENVLESS_TOKEN", KEY: "ENVLESS_KEY", PASSPHRASE: "ENVLESS_PASSPHRASE", PRODUCT: "ENVLESS_PRODUCT",
+        PROJECT: "ENVLESS_PROJECT", ENV: "ENVLESS_ENV", DISABLE_UPDATE_NOTICE: "ENVLESS_DISABLE_UPDATE_NOTICE"
+      }
+      MACHINE_TOKEN_PREFIX = "ev_sk_"
+      VAR_TYPES = {STRING: "string", NUMBER: "number", BOOLEAN: "boolean"}
+      VISIBILITY = {SERVER: "server", CLIENT: "client"}
+      DEFAULT_TYPE = VAR_TYPES[:STRING]
+      DEFAULT_VISIBILITY = VISIBILITY[:SERVER]
+      CACHE_MAX_AGE = 900
+      CACHE_NO_PRODUCT = "_"
+      CACHE_UNSAFE_CHARACTERS = /[^a-zA-Z0-9._-]/
+      CONFIG_DIR = ".envless"
+      CONFIG_FILE = "config.json"
+      CACHE_DIR = "cache"
+      ENVLESS_FILE = ".envless"
+      DIR_MODE = 0o700
+      FILE_MODE = 0o600
+      PAGE_LIMIT = 100
+      INJECTED = {NAME: "ENVLESS_INJECTED", TYPE_KEY: "t", VISIBILITY_KEY: "v"}
+      UNSAFE_PROCESS_ENV_NAMES = %w[
+        NODE_OPTIONS NODE_PATH NODE_REPL_EXTERNAL_MODULE ELECTRON_RUN_AS_NODE LD_PRELOAD LD_LIBRARY_PATH LD_AUDIT
+        DYLD_INSERT_LIBRARIES DYLD_LIBRARY_PATH DYLD_FRAMEWORK_PATH PATH BUN_INSPECT BUN_INSPECT_CONNECT_TO
+        RUBYOPT RUBYLIB BUNDLE_GEMFILE GEM_HOME GEM_PATH PYTHONPATH PYTHONHOME PYTHONSTARTUP PYTHONUSERBASE PHPRC
+        PHP_INI_SCAN_DIR ENVLESS_CLIENT_ENV ENVLESS_INJECTED
+      ].freeze
+      UNSAFE_NAMES = UNSAFE_PROCESS_ENV_NAMES.map(&:downcase).freeze
+      USER_AGENT = "envless-env-ruby/#{VERSION}"
+      LOG_PREFIX = "[envless]"
+
+      constants.each { |name| Ractor.make_shareable(const_get(name)) }
+    end
+  end
+end

data/lib/envless/env/store.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Envless
+  module Env
+    class Store
+      def initialize
+        @values = {}
+        @meta = {}
+        @overrides = []
+        @loaded = false
+        @injected = false
+        @seeded = false
+        @lock = Monitor.new
+      end
+
+      def replace(record, meta)
+        guarded do
+          @values = record.dup
+          @meta = record.keys.to_h { |name| [name, meta.fetch(name) { default_meta }] }
+          @loaded = true
+        end
+      end
+
+      def has?(name)
+        guarded { @values.key?(name) || @overrides.any? { |layer| layer.key?(name) } }
+      end
+
+      def raw(name)
+        guarded do
+          layer = @overrides.reverse_each.find { |candidate| candidate.key?(name) }
+          layer ? layer[name] : @values[name]
+        end
+      end
+
+      def meta_of(name)
+        guarded { @meta.fetch(name) { default_meta } }
+      end
+
+      def keys
+        guarded { (@values.keys + @overrides.flat_map(&:keys)).uniq }
+      end
+
+      def readable?
+        guarded { @loaded || !keys.empty? }
+      end
+
+      def injected?
+        guarded { @injected }
+      end
+
+      def snapshot
+        guarded { keys.filter_map { |name| (value = raw(name)) && [name, value] }.to_h }
+      end
+
+      def push(layer)
+        guarded { @overrides << layer }
+      end
+
+      def pop(layer)
+        guarded do
+          index = @overrides.rindex { |candidate| candidate.equal?(layer) }
+          @overrides.delete_at(index) if index
+          nil
+        end
+      end
+
+      private
+
+      def guarded
+        @lock.synchronize do
+          seed unless @seeded
+          yield
+        end
+      end
+
+      def default_meta
+        {type: Settings::DEFAULT_TYPE, visibility: Settings::DEFAULT_VISIBILITY}
+      end
+
+      def seed
+        @seeded = true
+        injected = Injected.seed
+        return if injected.nil?
+
+        @values, @meta = injected
+        @loaded = true
+        @injected = true
+      end
+    end
+  end
+end

data/lib/envless/env/target.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Envless
+  module Env
+    Target = Data.define(:workspace, :product, :project, :environment)
+
+    class Target
+      def self.resolve(binding = Binding.read)
+        product = Files.variable(Settings::ENV_VARS[:PRODUCT]) || binding&.product
+        project = Files.variable(Settings::ENV_VARS[:PROJECT]) || binding&.project
+        environment = Files.variable(Settings::ENV_VARS[:ENV]) || binding&.environments&.first
+        raise LoadError, Messages::PROJECT_MISSING if project.nil? || project.empty?
+        raise LoadError, Messages::ENVIRONMENT_MISSING if environment.nil? || environment.empty?
+
+        new(workspace: binding&.workspace, product: Files.text?(product) ? product : nil, project:, environment:)
+      end
+    end
+  end
+end

data/lib/envless/env/types/collect.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Envless
+  module Env
+    module Types
+      module Collect
+        module_function
+
+        def call(project: nil, product: nil, env: nil)
+          manifest = from_manifest
+          return manifest if manifest
+
+          token = Credentials.machine_token
+          binding = Binding.read
+          product = first(product, Files.variable(Settings::ENV_VARS[:PRODUCT]), binding&.product)
+          project = first(project, Files.variable(Settings::ENV_VARS[:PROJECT]), binding&.project)
+          slugs = slugs(env) || slugs(Files.variable(Settings::ENV_VARS[:ENV])) || binding&.environments
+          raise LoadError, Messages::PROJECT_MISSING if project.nil?
+          raise LoadError, Messages::ENVIRONMENT_MISSING if slugs.nil? || slugs.empty?
+
+          from_api(token, project, slugs, product)
+        end
+
+        def from_manifest
+          seeded = Injected.seed
+          return nil if seeded.nil?
+
+          record, meta = seeded
+          record.keys.map { |name| Declared.build(name, meta.fetch(name)[:type], meta.fetch(name)[:visibility]) }
+        end
+
+        def from_api(token, project, slugs, product)
+          api = Api.new(token)
+          begin
+            slugs.flat_map { |slug| declared(api, Target.new(workspace: nil, product:, project:, environment: slug)) }
+          ensure
+            api.close
+          end
+        end
+
+        def declared(api, target)
+          api.variables(target).map { |variable| Declared.build(variable[:name], variable[:type], variable[:visibility]) }
+        rescue Envless::Error, ArgumentError => error
+          raise LoadError, format(Messages::FETCH_FAILED, project: target.project, environment: target.environment,
+            reason: error.message)
+        end
+
+        def first(*candidates)
+          candidates.find { |candidate| Files.text?(candidate) }
+        end
+
+        def slugs(value)
+          listed = value.to_s.split(",").map(&:strip).reject(&:empty?)
+          listed.empty? ? nil : listed
+        end
+      end
+    end
+  end
+end

data/lib/envless/env/types/command.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Envless
+  module Env
+    module Types
+      module Command
+        OUTPUT = "sig/envless-env.rbs"
+        PREFIX = "envless-env types:"
+        USAGE = "Usage: envless-env types [--output PATH] [--project SLUG] [--product SLUG] [--env SLUGS] [--check]"
+        RUN_HINT = "Or run it under envless run, which needs no machine key: envless run -- bundle exec envless-env types"
+
+        module_function
+
+        def call(arguments, out: $stdout, err: $stderr)
+          command, *rest = arguments
+          return report(out, USAGE, 0) if %w[-h --help help].include?(command)
+          return report(out, VERSION, 0) if %w[-v --version].include?(command)
+          return report(err, USAGE, 2) unless command == "types"
+
+          run(parse(rest), out, err)
+        rescue OptionParser::ParseError => error
+          report(err, "#{PREFIX} #{error.message}\n#{USAGE}", 2)
+        end
+
+        def parse(arguments)
+          # @type var options: Hash[Symbol, untyped]
+          options = {output: OUTPUT, check: false}
+          OptionParser.new do |parser|
+            %i[output project product env].each { |name| parser.on("--#{name} VALUE", String) { |value| options[name] = value } }
+            parser.on("--check") { options[:check] = true }
+          end.parse!(arguments.dup)
+          options
+        end
+
+        def run(options, out, err)
+          declared = Collect.call(project: options[:project], product: options[:product], env: options[:env])
+          write(options[:output].to_s, Render.call(declared), Declared.merged(declared).size, options[:check] == true, out, err)
+        rescue LoadError => error
+          hint = error.message.include?(Settings::ENV_VARS[:TOKEN]) ? "\n#{RUN_HINT}" : ""
+          report(err, "#{PREFIX} #{error.message}#{hint}", 1)
+        end
+
+        def write(path, text, count, check, out, err)
+          current = File.file?(path) ? File.read(path, encoding: Encoding::UTF_8) : nil
+          if check
+            return report(out, "#{PREFIX} #{path} is current, #{count} variables.", 0) if current == text
+
+            return report(err, "#{PREFIX} #{path} is stale. Run bundle exec envless-env types.", 1)
+          end
+          unless current == text
+            FileUtils.mkdir_p(File.dirname(path))
+            File.write(path, text)
+          end
+          report(out, "#{PREFIX} #{count} variables in #{path}.", 0)
+        end
+
+        def report(stream, message, code)
+          stream.puts(message)
+          code
+        end
+      end
+    end
+  end
+end

data/lib/envless/env/types/declared.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Envless
+  module Env
+    module Types
+      Declared = Data.define(:name, :type, :visibility)
+
+      class Declared
+        RUBY_TYPES = {"number" => "(Integer | Float)", "boolean" => "bool"}.freeze
+        LITERAL = /\A[A-Za-z_][A-Za-z0-9_]*\z/
+
+        def self.build(name, type, visibility)
+          new(name:, type: known(type, Settings::VAR_TYPES, Settings::DEFAULT_TYPE),
+            visibility: known(visibility, Settings::VISIBILITY, Settings::DEFAULT_VISIBILITY))
+        end
+
+        def self.known(value, allowed, fallback)
+          (value.is_a?(String) && allowed.value?(value)) ? value : fallback
+        end
+
+        def self.merged(declared)
+          declared.uniq(&:name).sort_by(&:name)
+        end
+
+        def rbs(optional)
+          "#{RUBY_TYPES.fetch(type, "String")}#{"?" if optional}"
+        end
+
+        def client?
+          visibility == Settings::VISIBILITY[:CLIENT]
+        end
+
+        def method?
+          Values::READABLE.match?(name)
+        end
+
+        def literal?
+          LITERAL.match?(name)
+        end
+      end
+    end
+  end
+end

data/lib/envless/env/types/render.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Envless
+  module Env
+    module Types
+      module Render
+        HEADER = ["# Generated by envless-env. Do not edit it by hand.",
+          "# Run `bundle exec envless-env types` to regenerate it."].freeze
+        VIEWS = {
+          "Server" => {client: false, optional: false, views: %w[Optional Client]},
+          "Optional" => {client: false, optional: true, views: %w[Optional ClientOptional]},
+          "Client" => {client: true, optional: false, views: %w[ClientOptional Client]},
+          "ClientOptional" => {client: true, optional: true, views: %w[ClientOptional ClientOptional]}
+        }
+        FALLBACK = "(String | Symbol name) -> value?"
+
+        constants.each { |name| Ractor.make_shareable(const_get(name)) }
+
+        module_function
+
+        def call(declared)
+          entries = Declared.merged(declared)
+          [*HEADER, *untyped(entries), "", "module Envless", "  def self.env: () -> Env::Typed::Server | ...", "",
+            "  module Env", "    def self.values: () -> Typed::Server | ...", "    def self.optional: () -> Typed::Optional | ...",
+            "    def self.client: () -> Typed::Client | ...", "", "    module Typed",
+            *VIEWS.flat_map { |name, view| view(name, view, entries) }, "    end", "  end", "end", ""].join("\n")
+        end
+
+        def untyped(entries)
+          names = entries.reject(&:literal?).map(&:name)
+          names.empty? ? [] : ["# Read these through Envless.env[\"NAME\"], untyped: #{names.join(", ")}"]
+        end
+
+        def view(name, view, entries)
+          shown = entries.select { |entry| !view[:client] || entry.client? }
+          optional = view[:optional]
+          optional_view, client_view = view[:views]
+          lines = ["      class #{name} < Values", "        def optional: () -> #{optional_view}",
+            "        def client: () -> #{client_view}", *index(shown, optional)]
+          lines += shown.select(&:method?).map { |entry| "        def #{entry.name}: () -> #{entry.rbs(optional)}" }
+          [*lines, "      end", *((name == "ClientOptional") ? [] : [""])]
+        end
+
+        def index(entries, optional)
+          overloads = entries.select(&:literal?).map { |entry| "(:#{entry.name} | \"#{entry.name}\") -> #{entry.rbs(optional)}" }
+          first, *rest = [*overloads, FALLBACK]
+          ["        def []: #{first}", *rest.map { |overload| "              | #{overload}" }]
+        end
+      end
+    end
+  end
+end

data/lib/envless/env/types.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../env"
+
+%w[declared collect render command].each { |name| require_relative "types/#{name}" }