konfidant 0.7.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d76590436720d9998f06a04fffa4a5a06b3aff597c675e6b4a1eafe770cd383f
+  data.tar.gz: 2e09ccdb885e047fdefe69faeba3289a919052534d07ef0bc5040a0e91256b14
+SHA512:
+  metadata.gz: 6e858d0172471e5e88261696bc2201307e582f4003eb588ee6308fb0c1e2d280c72e6673b5329c00b2efc64b204a4abb9adacd848700d6a2daaeb04fe491a5c1
+  data.tar.gz: 1ecd149e3f5efed0fb906b75499789610b5305dbb816b95dbad72074a022937a1f42126556faedd248d9a96e71a5c8e40d87fbb06e4cb2f4f1736cf443b9a691

data/README.md

@@ -0,0 +1,343 @@
+# konfidant-ruby
+
+[![Test](https://github.com/konfidant/sdk-ruby/actions/workflows/test.yml/badge.svg)](https://github.com/konfidant/sdk-ruby/actions/workflows/test.yml)
+[![Codacy Badge](https://app.codacy.com/project/badge/Grade/eb3798f7eb59412abc2bd3ce307760b5)](https://app.codacy.com/gh/konfidant/sdk-ruby/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
+[![Codacy Badge](https://app.codacy.com/project/badge/Coverage/eb3798f7eb59412abc2bd3ce307760b5)](https://app.codacy.com/gh/konfidant/sdk-ruby/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage)
+
+Official Ruby SDK for the [Konfidant](https://www.konfidant.app) API.
+
+Konfidant lets you share secrets — encrypted text and files — that self-destruct after being read.
+
+---
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem 'konfidant'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install konfidant
+```
+
+---
+
+## Quick start
+
+```ruby
+require 'konfidant'
+
+client = Konfidant::Client.new(api_key: 'your-api-key')
+
+result = client.share_text(text: 'super-secret-password', ttl_hours: 24)
+
+puts "Share this link: #{result.share_url}"
+```
+
+---
+
+## Authentication
+
+All requests require a Bearer API key. Generate one from the [Konfidant dashboard](https://www.konfidant.app).
+
+```ruby
+client = Konfidant::Client.new(api_key: ENV['KONFIDANT_API_KEY'])
+```
+
+---
+
+## API Reference
+
+### `Konfidant::Client.new`
+
+| Option         | Type      | Required | Description                                                          |
+|----------------|-----------|----------|----------------------------------------------------------------------|
+| `api_key`      | `String`  | Yes      | Your Konfidant API key                                               |
+| `base_url`     | `String`  | No       | Override the base URL (default: `https://www.konfidant.app`)         |
+| `http_timeout` | `Integer` | No       | Per-request HTTP timeout in seconds (default: `120`; `nil` disables) |
+
+Raises `ArgumentError` if `api_key` is nil or empty.
+
+---
+
+### `client.share_text(text:, ttl_hours:)`
+
+Encrypt and share a text message.
+
+| Argument    | Type      | Description              |
+|-------------|-----------|--------------------------|
+| `text`      | `String`  | The secret text to share |
+| `ttl_hours` | `Integer` | Time-to-live in hours    |
+
+Returns a `Konfidant::ShareTextResponse`:
+
+| Field          | Type      | Description                                 |
+|----------------|-----------|---------------------------------------------|
+| `text_id`      | `String`  | Unique ID of the shared text                |
+| `share_url`    | `String`  | One-time download link to send to recipient |
+| `expires_at`   | `String`  | Expiry datetime                             |
+| `verified_burn`| `Boolean` | Whether burn-on-read is verified            |
+
+#### Example: share text
+
+```ruby
+result = client.share_text(text: 'db-password: hunter2', ttl_hours: 48)
+
+puts result.share_url    # send to recipient
+puts result.expires_at
+puts result.verified_burn
+```
+
+---
+
+### `client.share_file(filename:, file_size:, ttl_hours:)`
+
+Request a presigned upload URL for a file. Use the returned response with `upload_file` to complete
+the upload, then poll `get_file_status` for the share link.
+
+> For a one-call convenience wrapper, see [`share_and_upload_file`](#clientshare_and_upload_file).
+
+| Argument    | Type      | Description                      |
+|-------------|-----------|----------------------------------|
+| `filename`  | `String`  | Original filename with extension |
+| `file_size` | `Integer` | File size in bytes               |
+| `ttl_hours` | `Integer` | Time-to-live in hours            |
+
+Returns a `Konfidant::ShareFileResponse`:
+
+| Field              | Type                          | Description                                     |
+|--------------------|-------------------------------|-------------------------------------------------|
+| `upload_url`       | `String`                      | Short-lived presigned S3 PUT URL                |
+| `file_key`         | `String`                      | Use with `get_file_status` and `upload_file`    |
+| `poll_url`         | `String`                      | Convenience URL for status polling              |
+| `metadata_headers` | `Konfidant::FileMetadataHeaders` | Required S3 headers — passed by `upload_file` |
+
+---
+
+### `client.upload_file(io:, size:, content_type:, presigned:)`
+
+Upload file bytes to the presigned S3 URL from `share_file`. Automatically attaches the required
+S3 metadata headers. Does **not** send the Konfidant `Authorization` header to S3.
+
+| Argument       | Type                        | Description                           |
+|----------------|-----------------------------|---------------------------------------|
+| `io`           | `IO`                        | Readable IO object (File, StringIO)   |
+| `size`         | `Integer`                   | Content-Length in bytes               |
+| `content_type` | `String`                    | MIME type (e.g. `application/pdf`)    |
+| `presigned`    | `Konfidant::ShareFileResponse` | Full response from `share_file`    |
+
+Returns `nil` on success. Raises `Konfidant::ApiError` on S3 error.
+
+#### Example: manual three-step flow
+
+```ruby
+file = File.open('report.pdf', 'rb')
+size = File.size('report.pdf')
+
+# Step 1 – get presigned URL
+presigned = client.share_file(
+  filename:  'report.pdf',
+  file_size: size,
+  ttl_hours: 72
+)
+
+# Step 2 – upload to S3
+client.upload_file(
+  io:           file,
+  size:         size,
+  content_type: 'application/pdf',
+  presigned:    presigned
+)
+
+# Step 3 – poll for share link
+loop do
+  status = client.get_file_status(presigned.file_key)
+  if status.status == 'complete'
+    puts "Share URL: #{status.share_url}"
+    break
+  end
+  sleep 2
+end
+```
+
+---
+
+### `client.get_file_status(file_key)`
+
+Poll the encryption status of an uploaded file.
+
+| Argument   | Type     | Description                                   |
+|------------|----------|-----------------------------------------------|
+| `file_key` | `String` | The `file_key` from the `share_file` response |
+
+Returns a `Konfidant::FileStatusResponse`:
+
+| Field          | Type      | When set                                |
+|----------------|-----------|-----------------------------------------|
+| `status`       | `String`  | Always (`"processing"` or `"complete"`) |
+| `message`      | `String`  | When `processing`                       |
+| `file_id`      | `String`  | When `complete`                         |
+| `file_name`    | `String`  | When `complete`                         |
+| `share_url`    | `String`  | When `complete`                         |
+| `expires_at`   | `String`  | When `complete`                         |
+| `verified_burn`| `Boolean` | When `complete`                         |
+
+---
+
+### `client.list_shares(type: nil, status: nil, limit: nil, offset: nil)`
+
+List all shares for the authenticated organization. All parameters are optional.
+
+| Argument | Type     | Description                    |
+|----------|----------|--------------------------------|
+| `type`   | `String` | `"file"` or `"text"`           |
+| `status` | `String` | `"active"` or `"accessed"`     |
+| `limit`  | `Integer`| Page size (default 50)         |
+| `offset` | `Integer`| Pagination offset              |
+
+Returns a `Konfidant::ListSharesResponse`:
+
+| Field        | Type                       | Description         |
+|--------------|----------------------------|---------------------|
+| `shares`     | `Array<Konfidant::Share>`  | Share entries       |
+| `pagination` | `Konfidant::Pagination`    | Page metadata       |
+
+Each `Konfidant::Share`:
+
+| Field            | Type          | Description             |
+|------------------|---------------|-------------------------|
+| `type`           | `String`      | `"file"` or `"text"`    |
+| `file_name`      | `String`      | Filename or text label  |
+| `file_size_bytes`| `Integer`     | Size in bytes           |
+| `created_at`     | `String`      | Creation datetime       |
+| `expires_at`     | `String`      | Expiry datetime         |
+| `accessed_at`    | `String, nil` | Access datetime, or nil |
+| `created_by`     | `String`      | Email of creator        |
+
+`Konfidant::Pagination`:
+
+| Field      | Type      | Description              |
+|------------|-----------|--------------------------|
+| `total`    | `Integer` | Total number of shares   |
+| `limit`    | `Integer` | Page size used           |
+| `offset`   | `Integer` | Offset used              |
+| `has_more` | `Boolean` | Whether more pages exist |
+
+#### Example: list shares
+
+```ruby
+result = client.list_shares(type: 'file', limit: 10)
+
+result.shares.each do |share|
+  puts "#{share.file_name} — expires #{share.expires_at}"
+end
+
+puts "Total: #{result.pagination.total}"
+puts "More? #{result.pagination.has_more}"
+```
+
+---
+
+### `client.share_and_upload_file`
+
+Convenience wrapper that calls `share_file` → `upload_file` → polls `get_file_status` until complete.
+
+```ruby
+client.share_and_upload_file(
+  io:            io,
+  size:          size,
+  filename:      filename,
+  content_type:  content_type,
+  ttl_hours:     ttl_hours,
+  poll_interval: 2,   # seconds between status checks (default: 2)
+  timeout:       60   # max wait for encryption in seconds (default: 60)
+)
+```
+
+| Argument        | Type      | Default | Description                         |
+|-----------------|-----------|---------|-------------------------------------|
+| `io`            | `IO`      | —       | Readable IO object (File, StringIO) |
+| `size`          | `Integer` | —       | File size in bytes                  |
+| `filename`      | `String`  | —       | Filename with extension             |
+| `content_type`  | `String`  | —       | MIME type                           |
+| `ttl_hours`     | `Integer` | —       | Time-to-live in hours               |
+| `poll_interval` | `Numeric` | `2`     | Seconds between status checks       |
+| `timeout`       | `Numeric` | `60`    | Max seconds to wait for encryption  |
+
+Returns a `Konfidant::ShareResult`:
+
+| Field          | Type      | Description                    |
+|----------------|-----------|--------------------------------|
+| `share_url`    | `String`  | One-time download link         |
+| `file_id`      | `String`  | Unique file ID                 |
+| `expires_at`   | `String`  | Expiry datetime                |
+| `verified_burn`| `Boolean` | Whether burn-on-read is active |
+
+Raises `RuntimeError` with `"konfidant: encryption timed out after Ns"` if encryption does not complete
+within `timeout` seconds.
+
+#### Example: share and upload file
+
+```ruby
+file = File.open('confidential.zip', 'rb')
+size = File.size('confidential.zip')
+
+result = client.share_and_upload_file(
+  io:           file,
+  size:         size,
+  filename:     'confidential.zip',
+  content_type: 'application/zip',
+  ttl_hours:    48
+)
+
+puts "Ready to share: #{result.share_url}"
+```
+
+---
+
+## Error handling
+
+All API and S3 errors raise `Konfidant::ApiError`.
+
+```ruby
+begin
+  client.share_text(text: 'secret', ttl_hours: 1)
+rescue Konfidant::ApiError => e
+  puts e.message     # e.g. "Missing or invalid Authorization header."
+  puts e.status_code # e.g. 401
+  puts e.body.inspect # parsed response body (Hash or String)
+end
+```
+
+### Common error codes
+
+| Status | Meaning                    |
+|--------|----------------------------|
+| `400`  | Bad request / invalid body |
+| `401`  | Missing or invalid API key |
+| `403`  | Insufficient API key scope |
+| `404`  | Resource not found         |
+
+---
+
+## Development
+
+```bash
+bundle install    # install dependencies
+bundle exec rspec # run tests
+```
+
+### Requirements
+
+- Ruby >= 3.2.0
+- No runtime dependencies (uses stdlib `net/http`, `uri`, `json`)

data/lib/konfidant/client.rb

@@ -0,0 +1,185 @@
+require 'net/http'
+require 'uri'
+require 'json'
+
+module Konfidant
+  DEFAULT_BASE_URL = 'https://www.konfidant.app'
+  DEFAULT_TIMEOUT  = 120
+
+  class Client
+    def initialize(api_key:, base_url: nil, http_timeout: DEFAULT_TIMEOUT)
+      raise ArgumentError, 'api_key is required' if api_key.nil? || api_key.empty?
+
+      @api_key      = api_key
+      @base_url     = (base_url || DEFAULT_BASE_URL).sub(%r{/+\z}, '')
+      @http_timeout = http_timeout
+    end
+
+    def share_text(text:, ttl_hours:)
+      body = request(:post, '/api/v1/texts', { text: text, ttl_hours: ttl_hours })
+      ShareTextResponse.new(
+        text_id:      body['text_id'],
+        share_url:    body['share_url'],
+        expires_at:   body['expires_at'],
+        verified_burn: body['verified_burn']
+      )
+    end
+
+    def share_file(filename:, file_size:, ttl_hours:)
+      body = request(:post, '/api/v1/files', { filename: filename, file_size: file_size, ttl_hours: ttl_hours })
+      h = body['metadata_headers']
+      ShareFileResponse.new(
+        upload_url:       body['upload_url'],
+        file_key:         body['file_key'],
+        metadata_headers: FileMetadataHeaders.new(
+          user_id:         h['x-amz-meta-user-id'],
+          ttl_hours:       h['x-amz-meta-ttl-hours'],
+          organization_id: h['x-amz-meta-organization-id']
+        ),
+        poll_url: body['poll_url']
+      )
+    end
+
+    def get_file_status(file_key)
+      encoded = encode_path_segment(file_key)
+      body = request(:get, "/api/v1/files/#{encoded}/status")
+      FileStatusResponse.new(
+        status:        body['status'],
+        message:       body['message'],
+        file_id:       body['file_id'],
+        file_name:     body['file_name'],
+        share_url:     body['share_url'],
+        expires_at:    body['expires_at'],
+        verified_burn: body['verified_burn']
+      )
+    end
+
+    def list_shares(type: nil, status: nil, limit: nil, offset: nil)
+      params = {}
+      params[:type]   = type   if type
+      params[:status] = status if status
+      params[:limit]  = limit  if limit
+      params[:offset] = offset if offset
+
+      path = '/api/v1/shares'
+      path += "?#{URI.encode_www_form(params)}" unless params.empty?
+
+      body = request(:get, path)
+      ListSharesResponse.new(
+        shares:     body['shares'].map { |s| parse_share(s) },
+        pagination: parse_pagination(body['pagination'])
+      )
+    end
+
+    def upload_file(io:, size:, content_type:, presigned:)
+      uri  = URI.parse(presigned.upload_url)
+      http = build_http(uri)
+
+      req = Net::HTTP::Put.new(uri.request_uri)
+      req['Content-Type']               = content_type
+      req['Content-Length']             = size.to_s
+      req['x-amz-meta-organization-id'] = presigned.metadata_headers.organization_id
+      req['x-amz-meta-ttl-hours']       = presigned.metadata_headers.ttl_hours
+      req['x-amz-meta-user-id']         = presigned.metadata_headers.user_id
+      req.body_stream = io
+
+      resp = http.request(req)
+      return if resp.code.to_i.between?(200, 299)
+
+      raise ApiError.new("file upload failed: HTTP #{resp.code}", resp.code.to_i, resp.body)
+    end
+
+    def share_and_upload_file(io:, size:, filename:, content_type:, ttl_hours:,
+                              poll_interval: 2, timeout: 60)
+      presigned = share_file(filename: filename, file_size: size, ttl_hours: ttl_hours)
+      upload_file(io: io, size: size, content_type: content_type, presigned: presigned)
+
+      deadline = Time.now + timeout
+      while Time.now < deadline
+        status = get_file_status(presigned.file_key)
+        if status.status == 'complete'
+          return ShareResult.new(
+            share_url:    status.share_url,
+            file_id:      status.file_id,
+            expires_at:   status.expires_at,
+            verified_burn: status.verified_burn
+          )
+        end
+        sleep(poll_interval)
+      end
+
+      raise "konfidant: encryption timed out after #{timeout}s"
+    end
+
+    private
+
+    def auth_headers
+      {
+        'Authorization' => "Bearer #{@api_key}",
+        'Content-Type'  => 'application/json'
+      }
+    end
+
+    def build_http(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+      unless @http_timeout.nil?
+        http.open_timeout = @http_timeout
+        http.read_timeout = @http_timeout
+      end
+      http
+    end
+
+    def request(method, path, payload = nil)
+      uri  = URI.parse("#{@base_url}#{path}")
+      http = build_http(uri)
+
+      req = case method
+            when :get  then Net::HTTP::Get.new(uri.request_uri)
+            when :post then Net::HTTP::Post.new(uri.request_uri)
+            end
+
+      auth_headers.each { |k, v| req[k] = v }
+      req.body = JSON.generate(payload) if payload
+
+      resp         = http.request(req)
+      content_type = resp['content-type'] || ''
+
+      body = if content_type.include?('application/json')
+               JSON.parse(resp.body)
+             else
+               resp.body
+             end
+
+      return body if resp.code.to_i.between?(200, 299)
+
+      message = body.is_a?(Hash) && body['error'] ? body['error'] : "HTTP #{resp.code}"
+      raise ApiError.new(message, resp.code.to_i, body)
+    end
+
+    def encode_path_segment(str)
+      str.gsub(/[^A-Za-z0-9\-._~]/) { |c| c.bytes.map { |b| format('%%%02X', b) }.join }
+    end
+
+    def parse_share(s)
+      Share.new(
+        type:            s['type'],
+        file_name:       s['file_name'],
+        file_size_bytes: s['file_size_bytes'],
+        created_at:      s['created_at'],
+        expires_at:      s['expires_at'],
+        accessed_at:     s['accessed_at'],
+        created_by:      s['created_by']
+      )
+    end
+
+    def parse_pagination(p)
+      Pagination.new(
+        total:    p['total'],
+        limit:    p['limit'],
+        offset:   p['offset'],
+        has_more: p['has_more']
+      )
+    end
+  end
+end

data/lib/konfidant/errors.rb

@@ -0,0 +1,11 @@
+module Konfidant
+  class ApiError < StandardError
+    attr_reader :status_code, :body
+
+    def initialize(message, status_code, body)
+      super(message)
+      @status_code = status_code
+      @body        = body
+    end
+  end
+end

data/lib/konfidant/types.rb

@@ -0,0 +1,31 @@
+module Konfidant
+  FileMetadataHeaders = Data.define(:user_id, :ttl_hours, :organization_id)
+
+  ShareTextResponse = Data.define(:text_id, :share_url, :expires_at, :verified_burn)
+
+  ShareFileResponse = Data.define(:upload_url, :file_key, :metadata_headers, :poll_url)
+
+  FileStatusResponse = Data.define(
+    :status, :message, :file_id, :file_name, :share_url, :expires_at, :verified_burn
+  ) do
+    def initialize(status:, message: nil, file_id: nil, file_name: nil,
+                   share_url: nil, expires_at: nil, verified_burn: nil)
+      super
+    end
+  end
+
+  Share = Data.define(
+    :type, :file_name, :file_size_bytes, :created_at, :expires_at, :accessed_at, :created_by
+  ) do
+    def initialize(type:, file_name:, file_size_bytes:, created_at:,
+                   expires_at:, created_by:, accessed_at: nil)
+      super
+    end
+  end
+
+  Pagination = Data.define(:total, :limit, :offset, :has_more)
+
+  ListSharesResponse = Data.define(:shares, :pagination)
+
+  ShareResult = Data.define(:share_url, :file_id, :expires_at, :verified_burn)
+end

data/lib/konfidant/version.rb

@@ -0,0 +1,3 @@
+module Konfidant
+  VERSION = '0.7.0'
+end

data/lib/konfidant.rb

@@ -0,0 +1,4 @@
+require_relative 'konfidant/version'
+require_relative 'konfidant/errors'
+require_relative 'konfidant/types'
+require_relative 'konfidant/client'

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification
+name: konfidant
+version: !ruby/object:Gem::Version
+  version: 0.7.0
+platform: ruby
+authors:
+- Konfidant
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: simplecov-lcov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+email:
+- hello@konfidant.app
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/konfidant.rb
+- lib/konfidant/client.rb
+- lib/konfidant/errors.rb
+- lib/konfidant/types.rb
+- lib/konfidant/version.rb
+homepage: https://github.com/konfidant/sdk-ruby
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Official Ruby SDK for the Konfidant API
+test_files: []