bella_baxter 0.1.1.pre.preview.16

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cb3fc52da6617b4a90c7911111de5ee39a744bbaf008cef00a383aecd107fca6
+  data.tar.gz: fea83d2310a8526ca41cf8a0964662d8b3a5f0fa2331031fb4c5e7d6048052db
+SHA512:
+  metadata.gz: 354fa643232c8793947217234dc6f2eba3d9604016f1efdcb7e24b5da158dc5320adc55d8f1fc4f140d7f355a9aa40785f2366caa3a0baeb54fcfbfd2ad33b65
+  data.tar.gz: 40789fc9d388d71ffbf6be69dfd322078be025573fd7d24ecec809e8b1ac7697a226ff6e574ee07a158fbb9b657ff67e0dd79f61c64136cb74baff4dc6eb0ac2

data/README.md

@@ -0,0 +1,225 @@
+# bella_baxter Ruby SDK
+
+Ruby client for [Bella Baxter](https://github.com/cosmic-chimps/bella-baxter) — load secrets into your Ruby or Rails application with zero runtime dependencies.
+
+## Features
+
+- **Zero runtime dependencies** — uses only Ruby's stdlib (`openssl`, `net/http`, `json`)
+- **Rails Railtie** — auto-loads secrets before `database.yml` is evaluated
+- **End-to-end encryption** — optional E2EE using ECDH-P256-HKDF-SHA256-AES256GCM (stdlib OpenSSL)
+- **Thread-safe** — singleton client, mutex-protected HTTP
+- **ENV injection** — `load_into_env!` respects existing values (local dev overrides work)
+
+## Installation
+
+```ruby
+# Gemfile
+gem "bella_baxter"
+```
+
+```bash
+bundle install
+```
+
+## Quick start
+
+```ruby
+require "bella_baxter"
+
+client = BellaBaxter::Client.new(
+  baxter_url:  "https://baxter.example.com",
+  api_key:     "bax-...",
+  project:     "my-app",
+  environment: "production"
+)
+
+secrets = client.all_secrets.secrets
+puts secrets["DATABASE_URL"]
+```
+
+## Rails integration
+
+Add the gem to your Gemfile. That's all.
+
+The gem ships a **Railtie** that injects all secrets into `ENV` during Rails' `before_configuration` hook — before `database.yml` is parsed, before any initializers run.
+
+**Environment variables to set on your host** (the only secrets you need there):
+
+```bash
+BELLA_BAXTER_URL=https://baxter.example.com
+BELLA_API_KEY=bax-...
+BELLA_PROJECT=my-app
+# BELLA_ENV defaults to Rails.env
+# BELLA_E2EE=true  to enable end-to-end encryption
+```
+
+**database.yml** — nothing secret lives here:
+
+```yaml
+production:
+  adapter: postgresql
+  url: <%= ENV.fetch("DATABASE_URL") %>
+```
+
+`DATABASE_URL` is injected by Bella Baxter before Rails reads this file.
+
+### Boot order
+
+```
+1. Gemfile loaded        → Railtie registered
+2. config/application.rb starts
+3. [before_configuration] ← Bella Baxter injects ENV here
+4. database.yml evaluated ← ENV["DATABASE_URL"] available ✓
+5. config/initializers/
+6. App boots
+```
+
+## ENV injection
+
+```ruby
+# Inject into ENV (existing values are NOT overwritten — local dev wins)
+count = BellaBaxter.load_into_env!
+puts "Loaded #{count} secrets"
+
+# Force overwrite (e.g. secret rotation without restart)
+BellaBaxter.load_into_env!(overwrite: true)
+```
+
+## End-to-end encryption
+
+```ruby
+client = BellaBaxter::Client.new(
+  baxter_url:  "https://baxter.example.com",
+  api_key:     "bax-...",
+  project:     "my-app",
+  environment: "production",
+  enable_e2ee: true   # Client generates P-256 keypair; server encrypts the response
+)
+
+# Decryption is transparent — same API
+secrets = client.all_secrets.secrets
+```
+
+Algorithm: `ECDH-P256 → HKDF-SHA256 → AES-256-GCM`. All operations use Ruby's built-in `openssl` — no extra gems required.
+
+## Write operations
+
+```ruby
+# Create
+client.create_secret(
+  provider:    "my-vault",       # provider slug
+  key:         "DATABASE_URL",
+  value:       "postgres://...",
+  description: "Primary database"
+)
+
+# Update
+client.update_secret(
+  provider: "my-vault",
+  key:      "DATABASE_URL",
+  value:    "postgres://new-host/..."
+)
+
+# Delete
+client.delete_secret(provider: "my-vault", key: "DATABASE_URL")
+```
+
+## Lightweight version check
+
+Avoid transferring all secret values just to check if anything changed:
+
+```ruby
+v = client.secrets_version
+puts "Version #{v.version}, last changed #{v.last_modified}"
+```
+
+## Global configuration (optional)
+
+```ruby
+# config/initializers/bella_baxter.rb
+BellaBaxter.configure do |c|
+  c.baxter_url  = ENV["BELLA_BAXTER_URL"]
+  c.api_key     = ENV["BELLA_API_KEY"]
+  c.project     = "my-app"
+  c.environment = Rails.env
+  c.enable_e2ee = Rails.env.production?
+end
+
+# Access the singleton client anywhere
+BellaBaxter.client.all_secrets
+```
+
+## Samples
+
+| Sample | Description |
+|--------|-------------|
+| [`samples/01-standalone/`](samples/01-standalone/) | Pure Ruby script — all usage patterns |
+| [`samples/02-rails/`](samples/02-rails/) | Rails integration with `database.yml` example |
+
+---
+
+## Typed Secret Code Generation
+
+`bella secrets generate ruby` fetches the secrets manifest (key names + type hints, no values) from the Bella API and generates a typed `AppSecrets` module. Each method calls `ENV.fetch` at runtime — no secret values are ever embedded in the generated file.
+
+```bash
+bella secrets generate ruby \
+  --project my-app \
+  --environment production \
+  --output app_secrets.rb
+```
+
+**Generated `app_secrets.rb`:**
+
+```ruby
+# Auto-generated by bella secrets generate ruby — do not edit manually.
+
+module AppSecrets
+  def self.database_url
+    ENV.fetch('DATABASE_URL') { raise "Secret 'DATABASE_URL' is not set." }
+  end
+
+  def self.port
+    ENV.fetch('PORT') { raise "Secret 'PORT' is not set." }.to_i
+  end
+
+  def self.enable_feature_x
+    v = ENV.fetch('ENABLE_FEATURE_X') { raise "Secret 'ENABLE_FEATURE_X' is not set." }
+    %w[1 true yes].include?(v.downcase)
+  end
+end
+```
+
+### Usage alongside the Ruby SDK
+
+```ruby
+# The Railtie or BellaBaxter.load_into_env! has already populated ENV.
+require_relative "app_secrets"
+
+db_url  = AppSecrets.database_url    # String — raises if missing
+port    = AppSecrets.port            # Integer — parsed automatically
+```
+
+Because each method calls `ENV.fetch` on every invocation (not memoized), secrets injected or refreshed at any point are always current.
+
+### Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-p, --project <slug>` | `.bella` context | Project slug |
+| `-e, --environment <slug>` | `.bella` context | Environment slug |
+| `--provider <slug>` | `default` | Provider slug |
+| `-o, --output <path>` | `app_secrets.rb` | Output file path |
+| `--class-name <name>` | `AppSecrets` | Module name |
+| `--dry-run` | — | Print to stdout without writing |
+
+---
+
+## Requirements
+
+- Ruby >= 2.7
+- No runtime gem dependencies
+
+## License
+
+[Elastic License 2.0 (ELv2)](https://www.elastic.co/licensing/elastic-license)

data/lib/bella_baxter/client.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+require "digest"
+require "time"
+require "microsoft_kiota_faraday"
+require_relative "hmac_auth_provider"
+require_relative "e2ee_faraday_middleware"
+require_relative "models"
+require_relative "errors"
+require_relative "e2ee"
+
+# require generated Kiota client (generated by apps/sdk/generate.sh)
+begin
+  require_relative "generated/bella_client"
+rescue LoadError
+  # generated/ not present — run apps/sdk/generate.sh to generate the Kiota client
+end
+
+module BellaBaxter
+  # Thread-safe Bella Baxter API client backed by the Kiota-generated BellaClient.
+  #
+  # Instantiate once and reuse across requests (e.g. in a Rails initializer).
+  # End-to-end encryption is always enabled — secret values are never visible
+  # in plaintext over the wire.
+  #
+  # == Basic usage
+  #
+  #   client = BellaBaxter::Client.new(
+  #     baxter_url: "https://baxter.example.com",
+  #     api_key:    "bax-..."
+  #   )
+  #   secrets = client.all_secrets.secrets
+  #   ENV["DATABASE_URL"] = secrets["DATABASE_URL"]
+  #
+  # Prerequisites: run `apps/sdk/generate.sh` to generate `lib/bella_baxter/generated/` first.
+  class Client
+    # Convenience constructor — reads BELLA_API_KEY and BELLA_BAXTER_URL from ENV.
+    #
+    # @return [BellaBaxter::Client]
+    def self.from_env
+      new(
+        baxter_url: ENV.fetch("BELLA_BAXTER_URL", "https://api.bella-baxter.io"),
+        api_key:    ENV.fetch("BELLA_API_KEY")
+      )
+    end
+
+    # @param opts [Hash, BellaBaxter::Configuration]
+    def initialize(**opts)
+      config = opts.size == 1 && opts.key?(:config) ? opts[:config] : Configuration.new(**opts)
+
+      auth = HmacAuthProvider.new(config.api_key)
+
+      @conn = Faraday.new(url: config.baxter_url.chomp("/")) do |f|
+        f.headers["User-Agent"]     = "bella-ruby-sdk/1.0"
+        f.headers["X-Bella-Client"] = "bella-ruby-sdk"
+        f.use E2EEFaradayMiddleware
+        f.adapter :net_http
+      end
+
+      adapter = MicrosoftKiotaFaraday::FaradayRequestAdapter.new(auth, nil, nil, @conn)
+      adapter.set_base_url(config.baxter_url.chomp("/"))
+
+      @kiota  = BellaBaxterGenerated::BellaClient.new(adapter)
+      @config = config
+    end
+
+    # ── Key context (auto-discovery) ────────────────────────────────────────────
+
+    # Calls GET /api/v1/keys/me to discover the project + environment this key
+    # is scoped to. Result is cached for the lifetime of the client instance.
+    #
+    # @return [Hash] parsed JSON response with 'projectSlug', 'environmentSlug', etc.
+    def key_context
+      @key_context ||= begin
+        parts     = @config.api_key.split("-", 3)
+        key_id    = parts[1]
+        secret    = [parts[2]].pack("H*")
+        path      = "/api/v1/keys/me"
+        timestamp = Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ")
+        body_hash = Digest::SHA256.hexdigest("")
+        sts       = "GET\n#{path}\n\n#{timestamp}\n#{body_hash}"
+        signature = OpenSSL::HMAC.hexdigest("SHA256", secret, sts)
+
+        resp = @conn.get(path) do |req|
+          req.headers["Accept"]            = "application/json"
+          req.headers["X-Bella-Key-Id"]    = key_id
+          req.headers["X-Bella-Timestamp"] = timestamp
+          req.headers["X-Bella-Signature"] = signature
+        end
+        JSON.parse(resp.body)
+      end
+    end
+
+    # ── Secret reads ────────────────────────────────────────────────────────────
+
+    # Fetch all secrets. Project and environment are auto-discovered from the API key.
+    # Can be overridden via keyword args for advanced use cases.
+    #
+    # @return [BellaBaxter::AllSecretsResponse]
+    def all_secrets(project: nil, environment: nil)
+      ctx         = key_context
+      project     ||= ctx["projectSlug"]
+      environment ||= ctx["environmentSlug"]
+
+      resp = @kiota.api.v1.projects.by_id(project)
+        .environments.by_env_slug(environment).secrets.get.resume
+
+      secrets = resp&.secrets&.additional_data || {}
+
+      AllSecretsResponse.new(
+        environment_slug: resp&.environment_slug || environment,
+        environment_name: resp&.environment_name || "",
+        secrets:          secrets.transform_values(&:to_s),
+        version:          resp&.version || 0,
+        last_modified:    resp&.last_modified&.to_s || ""
+      )
+    end
+
+    # Convenience: fetch all secrets and return them as a plain Hash.
+    #
+    # @return [Hash<String, String>]
+    def pull_secrets(project: nil, environment: nil)
+      all_secrets(project: project, environment: environment).secrets
+    end
+
+    # Lightweight version check. Project/environment auto-discovered from the API key.
+    #
+    # @return [BellaBaxter::SecretsVersionResponse]
+    def secrets_version(project: nil, environment: nil)
+      ctx         = key_context
+      project     ||= ctx["projectSlug"]
+      environment ||= ctx["environmentSlug"]
+
+      resp = @kiota.api.v1.projects.by_id(project)
+        .environments.by_env_slug(environment).secrets.version.get.resume
+
+      SecretsVersionResponse.new(
+        environment_slug: resp&.environment_slug || environment,
+        version:          resp&.version || 0,
+        last_modified:    resp&.last_modified&.to_s || ""
+      )
+    end
+
+    # Convenience: load all secrets into ENV.
+    #
+    # Secrets that are already set in ENV are NOT overwritten (existing
+    # environment variables take precedence — useful for local dev overrides).
+    #
+    # @param overwrite [Boolean] force-overwrite existing ENV values (default: false)
+    # @return [Integer] number of secrets injected
+    def load_into_env!(project: nil, environment: nil, overwrite: false)
+      resp  = all_secrets(project: project, environment: environment)
+      count = 0
+      resp.secrets.each do |key, value|
+        next if !overwrite && ENV.key?(key)
+        ENV[key] = value
+        count   += 1
+      end
+      count
+    end
+
+    # Access the full Kiota API navigator for all other endpoints
+    # (TOTP, projects, providers, environments, etc.).
+    #
+    # Example:
+    #   client.client.api.v1.projects.by_id("my-app")
+    #     .environments.by_env_slug("prod").totp.get
+    def client
+      @kiota
+    end
+  end
+end

data/lib/bella_baxter/e2ee.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+require "json"
+
+module BellaBaxter
+  # End-to-end encryption using ECDH-P256-HKDF-SHA256-AES256GCM.
+  #
+  # The client generates a P-256 keypair on initialization and sends
+  # +X-E2E-Public-Key+ with every secrets request. The server encrypts
+  # the response payload; this class transparently decrypts it.
+  #
+  # No extra gems required — uses Ruby's built-in +openssl+ stdlib.
+  module E2EE
+    class KeyPair
+      # Base64-encoded DER/SPKI public key to send as X-E2E-Public-Key header.
+      attr_reader :public_key_b64
+
+      def initialize
+        @ec = OpenSSL::PKey::EC.generate("prime256v1")
+
+        # Export public key in SubjectPublicKeyInfo (SPKI/DER) format — what the server expects.
+        # public_to_der is available in Ruby 3.0+ (openssl gem 3.x) via OpenSSL::PKey::PKey.
+        @public_key_b64 = Base64.strict_encode64(@ec.public_to_der)
+      end
+
+      # Decrypt a response payload.
+      #
+      # @param payload [Hash] Parsed JSON with keys:
+      #   encrypted, algorithm, serverPublicKey, nonce, tag, ciphertext
+      # @return [Hash] Decrypted secrets hash
+      # @raise [BellaBaxter::DecryptionError]
+      def decrypt(payload)
+        return payload unless payload["encrypted"] == true
+
+        server_key_der  = Base64.strict_decode64(payload["serverPublicKey"])
+        nonce           = Base64.strict_decode64(payload["nonce"])
+        tag             = Base64.strict_decode64(payload["tag"])
+        ciphertext      = Base64.strict_decode64(payload["ciphertext"])
+
+        # Load server public key from SPKI DER and compute ECDH shared secret.
+        # OpenSSL::PKey.read handles SPKI DER for all key types (Ruby 4.0 / openssl gem 4.x).
+        server_key      = OpenSSL::PKey.read(server_key_der)
+        shared_secret   = @ec.derive(server_key)
+
+        # HKDF-SHA256: extract + expand to 32-byte AES key.
+        key             = hkdf_sha256(shared_secret, 32)
+
+        # AES-256-GCM decrypt.
+        cipher          = OpenSSL::Cipher.new("aes-256-gcm")
+        cipher.decrypt
+        cipher.key      = key
+        cipher.iv       = nonce
+        cipher.auth_tag = tag
+        cipher.auth_data = ""
+
+        plaintext = cipher.update(ciphertext) + cipher.final
+        parsed = JSON.parse(plaintext)
+
+        # Three possible server response shapes:
+        #   1. Full AllEnvironmentSecretsResponse: {"environmentSlug":..., "secrets":{...}, ...}
+        #   2. Array of SecretItem:                [{"key":"K","value":"V"}, ...]
+        #   3. Legacy flat dict:                   {"K":"V", ...}
+        if parsed.is_a?(Hash) && parsed.key?("secrets") && parsed["secrets"].is_a?(Hash)
+          parsed["secrets"].transform_values(&:to_s)
+        elsif parsed.is_a?(Array)
+          parsed.each_with_object({}) do |item, h|
+            h[item["key"]] = item.fetch("value", "").to_s if item["key"]
+          end
+        else
+          parsed
+        end
+      rescue OpenSSL::Cipher::CipherError => e
+        raise BellaBaxter::DecryptionError, "AES-GCM decryption failed: #{e.message}"
+      rescue JSON::ParserError => e
+        raise BellaBaxter::DecryptionError, "Decrypted payload is not valid JSON: #{e.message}"
+      end
+
+      # Decrypt a response payload, returning the raw parsed JSON without transformation.
+      #
+      # Unlike +decrypt+, this preserves the full server response shape (including
+      # +environmentSlug+, +version+, +lastModified+, etc.).
+      #
+      # @param payload [Hash] Parsed JSON encrypted payload.
+      # @return [Hash] Full decrypted + parsed JSON hash.
+      # @raise [BellaBaxter::DecryptionError]
+      def decrypt_raw(payload)
+        return payload unless payload["encrypted"] == true
+
+        server_key_der = Base64.strict_decode64(payload["serverPublicKey"])
+        nonce          = Base64.strict_decode64(payload["nonce"])
+        tag            = Base64.strict_decode64(payload["tag"])
+        ciphertext     = Base64.strict_decode64(payload["ciphertext"])
+
+        server_key   = OpenSSL::PKey.read(server_key_der)
+        shared_secret = @ec.derive(server_key)
+        key          = hkdf_sha256(shared_secret, 32)
+
+        cipher           = OpenSSL::Cipher.new("aes-256-gcm")
+        cipher.decrypt
+        cipher.key       = key
+        cipher.iv        = nonce
+        cipher.auth_tag  = tag
+        cipher.auth_data = ""
+
+        plaintext = cipher.update(ciphertext) + cipher.final
+        JSON.parse(plaintext)
+      rescue OpenSSL::Cipher::CipherError => e
+        raise BellaBaxter::DecryptionError, "AES-GCM decryption failed: #{e.message}"
+      rescue JSON::ParserError => e
+        raise BellaBaxter::DecryptionError, "Decrypted payload is not valid JSON: #{e.message}"
+      end
+
+      private
+
+      # HKDF (RFC 5869) using HMAC-SHA256. Salt is 32 zero bytes (matches server).
+      def hkdf_sha256(ikm, length)
+        salt = "\x00" * 32
+        info = "bella-e2ee-v1"
+        prk  = OpenSSL::HMAC.digest("SHA256", salt, ikm)
+
+        t   = "".b
+        okm = "".b
+        n   = (length.to_f / 32).ceil
+
+        n.times do |i|
+          t   = OpenSSL::HMAC.digest("SHA256", prk, t + info + (i + 1).chr)
+          okm += t
+        end
+
+        okm[0, length]
+      end
+    end
+  end
+end

data/lib/bella_baxter/e2ee_faraday_middleware.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module BellaBaxter
+  # Faraday middleware that transparently adds E2EE to GET /secrets requests.
+  #
+  # On outbound: adds X-E2E-Public-Key header so the server encrypts the response.
+  # On inbound:  decrypts the encrypted payload and reconstructs a normal secrets response.
+  class E2EEFaradayMiddleware < Faraday::Middleware
+    def initialize(app)
+      super
+      @e2ee = E2EE::KeyPair.new
+    end
+
+    def call(env)
+      is_secrets_get = env.method == :get && env.url.path.end_with?("/secrets")
+
+      if is_secrets_get
+        env.request_headers["X-E2E-Public-Key"] = @e2ee.public_key_b64
+      end
+
+      @app.call(env).on_complete do |resp_env|
+        next unless is_secrets_get && resp_env.status == 200
+
+        data = JSON.parse(resp_env.body)
+        next unless data["encrypted"]
+
+        decrypted = @e2ee.decrypt_raw(data)
+        if decrypted.is_a?(Hash) && decrypted.key?("secrets") && decrypted["secrets"].is_a?(Hash)
+          resp_env[:body] = JSON.generate(decrypted)
+        else
+          secrets = @e2ee.decrypt(data)
+          resp_env[:body] = JSON.generate(
+            "secrets"         => secrets,
+            "version"         => 0,
+            "environmentSlug" => "",
+            "environmentName" => "",
+            "lastModified"    => ""
+          )
+        end
+      end
+    end
+  end
+end

data/lib/bella_baxter/errors.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module BellaBaxter
+  class Error < StandardError; end
+
+  # Raised when the API key format is invalid (must be bax-{keyId}-{signingSecret}).
+  class InvalidApiKeyError < Error; end
+
+  # Raised when the server returns a non-2xx response.
+  class ApiError < Error
+    attr_reader :status, :body
+
+    def initialize(status, body)
+      @status = status
+      @body   = body
+      super("Bella Baxter API error #{status}: #{body}")
+    end
+  end
+
+  # Raised when E2EE decryption fails.
+  class DecryptionError < Error; end
+
+  # Raised when required configuration is missing.
+  class ConfigurationError < Error; end
+
+  # Raised when webhook signature verification fails due to a malformed header
+  # or a timestamp that exceeds the tolerance window.
+  class WebhookSignatureError < Error; end
+end

data/lib/bella_baxter/generated/api/api_request_builder.rb

@@ -0,0 +1,52 @@
+require 'microsoft_kiota_abstractions'
+require_relative '../bella_baxter/generated'
+require_relative './api'
+require_relative './diagnostics/diagnostics_request_builder'
+require_relative './tenants/tenants_request_builder'
+require_relative './users/users_request_builder'
+require_relative './v1/v1_request_builder'
+require_relative './version/version_request_builder'
+
+module Bella_baxter/generated
+    module Api
+        ## 
+        # Builds and executes requests for operations under \api
+        class ApiRequestBuilder < MicrosoftKiotaAbstractions::BaseRequestBuilder
+            
+            ## 
+            # The diagnostics property
+            def diagnostics()
+                return Bella_baxter/generated::Api::Diagnostics::DiagnosticsRequestBuilder.new(@path_parameters, @request_adapter)
+            end
+            ## 
+            # The tenants property
+            def tenants()
+                return Bella_baxter/generated::Api::Tenants::TenantsRequestBuilder.new(@path_parameters, @request_adapter)
+            end
+            ## 
+            # The users property
+            def users()
+                return Bella_baxter/generated::Api::Users::UsersRequestBuilder.new(@path_parameters, @request_adapter)
+            end
+            ## 
+            # The v1 property
+            def v1()
+                return Bella_baxter/generated::Api::V1::V1RequestBuilder.new(@path_parameters, @request_adapter)
+            end
+            ## 
+            # The version property
+            def version()
+                return Bella_baxter/generated::Api::Version::VersionRequestBuilder.new(@path_parameters, @request_adapter)
+            end
+            ## 
+            ## Instantiates a new ApiRequestBuilder and sets the default values.
+            ## @param path_parameters Path parameters for the request
+            ## @param request_adapter The request adapter to use to execute the requests.
+            ## @return a void
+            ## 
+            def initialize(path_parameters, request_adapter)
+                super(path_parameters, request_adapter, "{+baseurl}/api")
+            end
+        end
+    end
+end