Encryption

Envless is end-to-end encrypted. The server stores ciphertext, cannot decrypt it, and cannot encrypt on your behalf. That is not a limitation to work around, it is the product, and it means the SDK does the cryptography locally, in your process, with the AES-GCM and PBKDF2 of Ruby's own OpenSSL.

require "envless/sdk"

passphrase = ENV.fetch("ENVLESS_PASSPHRASE")
workspace_id = Envless.me.get[:workspaceId]

ciphertext = Envless.encrypt_value("sk_live_51H...", passphrase,
  workspace_id)

Envless.variables.create("billing", "production",
  name: "STRIPE_SECRET_KEY", value: ciphertext)

require "envless/sdk"

passphrase = ENV.fetch("ENVLESS_PASSPHRASE")
workspace_id = Envless.me.get[:workspaceId]
variable = Envless.variables.get("billing", "production",
  "STRIPE_SECRET_KEY")
value = variable[:value]

if value
  puts Envless.decrypt_value(value, passphrase, workspace_id)
end

A value that cannot be decrypted, because the passphrase is wrong, the workspace id is wrong, or the text is not an Envless envelope, raises Envless::DecryptionError.

Plaintext, passphrases and workspace ids are encrypted as UTF-8. Text in another encoding, such as ISO-8859-1, is transcoded first, while bytes that are not valid UTF-8, such as binary data, raise ArgumentError rather than being changed silently, so encode binary data first, for example as base64.

The recipe#

Envless::ENCRYPTION_PARAMETERS holds the exact constants as a frozen Hash, the same values the TypeScript SDK exports, so any other implementation can match them byte for byte.

require "envless/sdk"

puts Envless::ENCRYPTION_PARAMETERS[:pbkdf2Iterations]

The salt is derived, not stored: SHA-256("envless:workspace:" + workspace_id) truncated to 16 bytes. That is why the workspace id is a required argument, and why decrypting with the wrong workspace id fails even when the passphrase is right.

A stored value is v1:base64(iv ‖ ciphertext). Older rows can carry v2:<iterations>:base64(iv ‖ ciphertext), which pins a non-default iteration count. decrypt_value reads both. encrypt_value always writes v1:. Ciphertext from this gem, the TypeScript and Python SDKs, the CLI and the dashboard is interchangeable in both directions.

require "envless/sdk"

puts Envless.ciphertext?("v1:8Wm3kQ...")
puts Envless.ciphertext?("v2:100000:8Wm3kQ...")
puts Envless.ciphertext?("sk_live_51H...")

ciphertext? takes any value and answers false for anything that is not a String carrying an Envless envelope, nil included.

Derive the key once for a batch#

PBKDF2 at 200,000 iterations is deliberately slow. encrypt_value and decrypt_value derive the key on every call, which is fine for one variable and wasteful for two hundred. Derive it once instead.

require "envless/sdk"

passphrase = ENV.fetch("ENVLESS_PASSPHRASE")
workspace_id = Envless.me.get[:workspaceId]
key = Envless.derive_workspace_key(passphrase, workspace_id)
variables = Envless.variables.list_all("billing", "production")

plaintext = variables.filter_map do |variable|
  value = variable[:value]
  [variable[:name], Envless.decrypt_with_key(key, value)] if value
end.to_h

puts plaintext.keys

encrypt_with_key(key, plaintext) is the matching direction, and both accept the Envless::WorkspaceKey returned by derive_workspace_key or import_workspace_key, or the raw 32 bytes as a binary String. Text is never taken for key bytes, so a passphrase passed by mistake raises ArgumentError instead of becoming a key.

Machine keys#

A workspace can also be unlocked with a raw 256-bit key instead of a passphrase, which is how CI runners avoid holding a human secret. import_workspace_key takes its base64url form, the ENVLESS_KEY a CI runner holds.

require "envless/sdk"

key = Envless.import_workspace_key(ENV.fetch("ENVLESS_KEY"))

puts key.inspect

A key of the wrong length raises ArgumentError immediately rather than producing garbage on first use. See Machine and CI access for how to obtain one.

Checking a passphrase#

passphrase_strength applies the rules rotate_workspace_passphrase enforces on a new passphrase, the same ones the TypeScript SDK exports, and returns an Envless::Validation rather than raising, so it fits a form or an onboarding script:

require "envless/sdk"

phrase = "correct horse battery staple"
check = Envless.passphrase_strength(phrase)

puts check.error unless check.valid?

Rotating a passphrase#

This is the operation people get wrong. Re-encrypting live variables and stopping there leaves version history encrypted with the old key, which silently breaks every later rollback: the rollback succeeds, and the restored values are undecryptable.

rotate_workspace_passphrase walks both.

require "envless/sdk"

workspace_id = Envless.me.get[:workspaceId]

result = Envless.rotate_workspace_passphrase(
  client: Envless.client,
  workspace_unique_id: workspace_id,
  from: ENV.fetch("ENVLESS_PASSPHRASE"),
  to: ENV.fetch("ENVLESS_NEW_PASSPHRASE"),
  project: "billing",
  environment: "production"
)

unless result.failures.empty?
  failed = result.failures.map(&:id).join(", ")
  abort "Rotation incomplete, keep the old passphrase: #{failed}"
end

puts "#{result.variables} variables"
puts "#{result.version_entries} version entries"

It re-encrypts every live variable value and default, then rewrites the version entries in batches of 100 through versions.reencrypt_entries. Needs variables:write and versions:write. client: takes any Envless::Client, and Envless.client hands you the shared one.

The result is an Envless::RotationResult. variables and version_entries count what was actually written, so a run that decrypts nothing reports zero rather than the number of rows it looked at. skipped lists the values that were not ciphertext and were left alone, and failures lists what could not be decrypted or what the API refused, each an Envless::RotationIssue with scope, id, field and reason. A version entry whose own value is empty or plaintext but whose defaultValue is ciphertext lands in failures too, with field set to "defaultValue", because the API only rewrites entries that carry a ciphertext value. to: is checked against the workspace passphrase rules before anything is written, and a weak one raises ArgumentError instead of re-encrypting your data behind a passphrase that will not hold.

Syncing a whole environment#

Do not loop over create, update and delete. variables.apply runs the entire change set in one transaction and detects concurrent edits through the baseline you send.

require "envless/sdk"

passphrase = ENV.fetch("ENVLESS_PASSPHRASE")
workspace_id = Envless.me.get[:workspaceId]
current = Envless.variables.list_all("billing", "production")

baseline = current.map do |variable|
  {
    uniqueId: variable[:id],
    name: variable[:name],
    updatedAt: variable[:updatedAt] || variable[:createdAt]
  }
end
flag = Envless.encrypt_value("true", passphrase, workspace_id)
old = current.select { |variable| variable[:name] == "OLD_FLAG" }

result = Envless.variables.apply("billing", "production",
  baseline:,
  creates: [{name: "NEW_FLAG", value: flag}],
  deletes: old.map { |variable| {uniqueId: variable[:id]} })

puts "#{result[:added]} added, #{result[:updated]} updated"
puts "#{result[:removed]} removed"

If anybody changed a variable since you read the baseline, the call fails with 409 variable.baseline_drifted and nothing is written. Re-read and retry.

What the server can and cannot see#

Names are searchable and appear in webhook payloads and audit history, so treat a variable name as public metadata. Put nothing sensitive in one.