konfidant-ruby

Official Ruby SDK for the Konfidant API.

Konfidant lets you share secrets — text and files — that self-destruct after being read.

All content is encrypted on your machine before anything is sent:

• Every share gets a fresh random 256-bit key. Text, file bytes, file name and MIME type are encrypted together with AES-256-GCM in the chunked KNF1 format (stdlib OpenSSL only).
• Konfidant receives only ciphertext and its size. It never sees the key, the content or the file name.
• The key lives only in the share link's URL fragment: https://download.konfidant.app/#t=<token>&k=<key>. Browsers never send the fragment to a server. The t token is single-use, so the ciphertext can be fetched once.
• Anyone holding the full share_url can read the secret once — treat it like the secret itself. If you lose it, the content cannot be recovered by anyone, including Konfidant.

gem 'konfidant'

bundle install   # or: gem install konfidant

Requires Ruby >= 3.2. No runtime dependencies (stdlib net/http, openssl, json).

require 'konfidant'

client = Konfidant::Client.new(api_key: ENV['KONFIDANT_API_KEY'])

text = client.share_text(text: 'db-password: hunter2', ttl_hours: 24)
puts text.share_url

file = File.open('contract.pdf', 'rb') do |f|
  client.share_file(content: f, filename: 'contract.pdf', content_type: 'application/pdf', ttl_hours: 48)
end
puts file.share_url

Raises ArgumentError if api_key is nil or empty.

Encrypts text (UTF-8, no SDK-side size limit; your plan's limit applies server-side) and uploads the ciphertext. ttl_hours is omitted from the request when nil (server default applies).

Encrypts and shares a file in one call: encrypt → create_file_upload → upload_ciphertext → complete_file_upload.

Use these when you need control over each step (e.g. your own retry logic).

key       = Konfidant::Knf.generate_key
encryptor = Konfidant::Knf.encryptor(key: key, content: File.open('a.zip', 'rb'), kind: 'file',
                                     name: 'a.zip', mime: 'application/zip')

upload = client.create_file_upload(ciphertext_size: encryptor.size, ttl_hours: 24)
client.upload_ciphertext(upload: upload, ciphertext: encryptor)   # String or IO-like
done   = client.complete_file_upload(file_key: upload.file_key)

share_url = Konfidant::Knf.build_share_url(done.download_url, key)

complete_file_upload raises ApiError with status 409 and message upload_incomplete if the PUT did not land. download_url contains only the token — append the key with Knf.build_share_url before sending it to anyone.

Recipient side. Sends only the token (POST https://<link host>/api/download, no API key, no decryption key), receives the ciphertext and decrypts it locally. Opening a share consumes it.

Raises ApiError (410) if the share was already opened or has expired, KnfError if the ciphertext does not authenticate (wrong key, modified or truncated data).

Returns shares (Array<Konfidant::Share> with type, file_size_bytes, created_at, expires_at, accessed_at, created_by) and pagination (total, limit, offset, has_more). File names are not available: the server never sees them.

The KNF1 implementation is public for advanced use and interoperability:

encrypt also accepts chunk_size: and a nonce_prefix: option that exists only for reproducing test vectors — never pass nonce_prefix in production.

All SDK errors inherit from Konfidant::Error.

begin
  client.share_text(text: 'secret', ttl_hours: 1)
rescue Konfidant::ApiError => e
  e.message      # the "error" field of the JSON body, e.g. "upload_incomplete", or "HTTP 500"
  e.status_code  # e.g. 401
  e.body         # parsed body (Hash) or raw String
rescue Konfidant::KnfError => e
  e.message      # encryption/decryption failure
end

bundle install
bundle exec rspec

spec/fixtures/knf1-test-vectors.json holds the cross-SDK KNF1 test vectors; the specs reproduce every ciphertext byte for byte.