zerodrop 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dce1e4e518096ffccfd4fdc04f743750b64230b58cd11e631b49ee116b1ad143
-  data.tar.gz: a847df3318ff736eb8500a1407b1e2d602c637f54e18dfb0959db2d1d786fc0c
+  metadata.gz: 8f2142d8cff25793a9e3449ebf8bf47ebb553ef0bfc4a2e3cf4403798ccaa36e
+  data.tar.gz: 57cdc59a7a7d60554f7db1b9caecae6430f93cea49a1a979dc6c04daad4cf4a5
 SHA512:
-  metadata.gz: a8bfc595cd95a7b75ed9c652c27ccea75353e25b7c4355d6512c514a000773eedc09749e107738d1820c6e71cef87f619a2f41b06ebeb9f253f42798ea555eae
-  data.tar.gz: 0fbf9f95d8772a227f9a2b46c2b9092238b9dbdb75f0ddbc8a835df83bd77f28cde57c6b9b966a66b2917da534b7b5d7382217e755eaff4ba7227edc02c2c8b3
+  metadata.gz: a1e838f2ae4fb4aa72fe1030ccbf55aea3e5b95f3e0667bae811ac36d180065b7f4ef26de2c1ff3c7578f2b475315d6359f0b3b22f14309ef0a2754f2071eb74
+  data.tar.gz: f882b41e4ff02f0882d39af36af3793a6e327f04ed7510f1b7d86bd6059230739f1a8505b23e4a2fd7eb47edf3b557771230ad30d52cef5adcc2997c7f175563

data/README.md

@@ -126,6 +126,21 @@ visit email.magic_link
 expect(page).to have_current_path("/dashboard")
 ```
 
+## Free API key (private inboxes)
+
+Without a key, anyone who knows an inbox's name can read it. With a free key, your inboxes start with your own prefix and only your key can read them.
+
+1. Sign in with GitHub at [zerodrop.dev/keys](https://zerodrop.dev/keys) and create a key.
+2. Set it as `ZERODROP_API_KEY`. The client reads it automatically, or you can pass `api_key:`.
+
+```ruby
+mail = ZeroDrop::Client.new   # reads ZERODROP_API_KEY when it's set
+mail.generate_inbox
+# => "k7x2-swift-x7k29ab@zerodrop-sandbox.online", where k7x2 is your prefix
+```
+
+Reading a `k7x2-…` inbox without your key raises `ZeroDrop::AuthError` with the reason. `mail.prefix` holds your prefix if you build an address yourself. A key holding a character that can't be sent in an HTTP header (a line break, a byte-order mark) makes `ZeroDrop::Client.new` raise `ArgumentError`; the message never includes the key.
+
 ## Parallel test runs
 
 `generate_inbox` runs locally — no network request, no collisions:
@@ -143,8 +158,8 @@ begin
   email = mail.wait_for_latest(inbox, timeout: 15)
 rescue ZeroDrop::TimeoutError
   # No email arrived — check your app is sending correctly
-rescue ZeroDrop::AuthError
-  # Invalid API key
+rescue ZeroDrop::AuthError => e
+  # The inbox belongs to another key's prefix, or your key is wrong — e.message says which
 rescue ZeroDrop::NetworkError => e
   # Transport failure — e.message includes status page link
 end
@@ -166,8 +181,9 @@ mail = ZeroDrop::Client.new(base_url: "https://your-instance.yourdomain.com")
 
 | Method | Description |
 |---|---|
-| `Client.new(api_key: nil, base_url: ...)` | Create a client. No args = free sandbox mode. |
-| `#generate_inbox` | Instant inbox address. No network request. |
+| `Client.new(api_key: nil, base_url: ...)` | Create a client. `api_key` defaults to `ENV["ZERODROP_API_KEY"]`; without a key, inboxes are public to anyone who knows the name. |
+| `#generate_inbox` | Instant inbox address. No network request. With a key, the name starts with your prefix. |
+| `#prefix` | Your key's inbox prefix (`"k7x2"`), or `nil` without a key. |
 | `#fetch_latest(inbox, filter: nil)` | Latest matching email or nil. |
 | `#wait_for_latest(inbox, timeout: 10, poll_interval: 2, filter: nil)` | Block until email arrives. |
 
@@ -181,6 +197,7 @@ mail = ZeroDrop::Client.new(base_url: "https://your-instance.yourdomain.com")
 | Email filtering | ✓ | ✓ |
 | Email retention | 30 min | Extended |
 | Custom domains | ✗ | ✓ |
+| API key | ✓ free at [zerodrop.dev/keys](https://zerodrop.dev/keys) | ✓ |
 
 Get a Workspace at [zerodrop.dev](https://zerodrop.dev)
 

data/lib/zerodrop/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ZeroDrop
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/zerodrop.rb

@@ -22,6 +22,18 @@ module ZeroDrop
   FREE_DOMAIN = "zerodrop-sandbox.online"
   ADJECTIVES = %w[swift dark cold null void zero dead raw base core].freeze
 
+  # A free key from https://zerodrop.dev/keys: zd_<prefix>_<32 letters/digits>.
+  # Inboxes named <prefix>-... can be read only with that key.
+  KEY_FORMAT = /\Azd_([a-z0-9]{4})_[A-Za-z0-9]{32}\z/
+
+  # A key goes into an HTTP header, so after trimming it may hold only visible
+  # ASCII. Anything else is refused without echoing the key.
+  KEY_CHARS = /\A[\x21-\x7e]+\z/
+
+  # Whitespace around a key, including the no-break spaces and byte-order
+  # marks that copying and pasting can bring along.
+  KEY_PADDING = /\A[[:space:]\0\u{FEFF}]+|[[:space:]\0\u{FEFF}]+\z/
+
   # Raised when no email arrives within the timeout.
   class TimeoutError < StandardError
     def initialize(inbox, timeout)
@@ -30,10 +42,11 @@ module ZeroDrop
     end
   end
 
-  # Raised when an invalid API key is provided.
+  # Raised on a 401: the inbox belongs to an account's prefix and the request
+  # had no key or the wrong one. The message carries the server's reason.
   class AuthError < StandardError
-    def initialize
-      super("invalid or missing API key")
+    def initialize(detail = nil)
+      super(detail || "invalid or missing API key")
     end
   end
 
@@ -74,21 +87,38 @@ module ZeroDrop
 
   # The ZeroDrop API client.
   class Client
-    # @param api_key [String, nil] Workspace API key. Omit for free sandbox mode.
+    # Your key's inbox prefix ("k7x2"), or nil without a key.
+    attr_reader :prefix
+
+    # @param api_key [String, nil] Free API key from https://zerodrop.dev/keys.
+    #   Defaults to ENV["ZERODROP_API_KEY"]. Without a key, anyone who knows
+    #   an inbox's name can read it.
     # @param base_url [String] Override for self-hosted instances.
+    # @raise [ArgumentError] if the key holds a character that can't be sent in
+    #   an HTTP header (a line break, a byte-order mark...)
     def initialize(api_key: nil, base_url: DEFAULT_BASE_URL)
-      @api_key = api_key
+      key = trim_key(api_key)
+      key = trim_key(ENV.fetch("ZERODROP_API_KEY", "")) if key.empty?
+      unless key.empty? || key.match?(KEY_CHARS)
+        raise ArgumentError, "ZeroDrop: the API key contains a character that can't be sent in an HTTP header, " \
+                             "such as a line break or a byte-order mark. Copy it again from https://zerodrop.dev/keys."
+      end
+      @api_key = key.empty? ? nil : key
+      @prefix = KEY_FORMAT.match(@api_key.to_s)&.[](1)
       @base_url = base_url.chomp("/")
     end
 
     # Returns a ready-to-use email address instantly.
-    # No network request is made.
+    # No network request is made. With a key, the name starts with your prefix.
     #
-    # @return [String] e.g. "swift-x7k29ab@zerodrop-sandbox.online"
+    # @return [String] e.g. "swift-x7k29ab@zerodrop-sandbox.online",
+    #   or "k7x2-swift-x7k29ab@zerodrop-sandbox.online" with the key zd_k7x2_...
     def generate_inbox
       adjective = ADJECTIVES.sample
       suffix = SecureRandom.alphanumeric(7).downcase
-      "#{adjective}-#{suffix}@#{FREE_DOMAIN}"
+      name = "#{adjective}-#{suffix}"
+      name = "#{@prefix}-#{name}" if @prefix
+      "#{name}@#{FREE_DOMAIN}"
     end
 
     # Returns the newest email matching the filter, or nil.
@@ -101,7 +131,7 @@ module ZeroDrop
       uri = URI("#{@base_url}/api/inbox/#{name}?source=ruby-sdk")
 
       res = http_get(uri)
-      raise AuthError if res.code == "401"
+      raise AuthError.new(error_detail(res)) if res.code == "401"
       raise NetworkError, "API returned #{res.code}" unless res.code == "200"
 
       payload = JSON.parse(res.body)
@@ -142,6 +172,16 @@ module ZeroDrop
 
     private
 
+    # ENV strings can arrive as binary or US-ASCII (no UTF-8 locale), so the
+    # bytes are read as UTF-8 before trimming.
+    def trim_key(value)
+      text = value.to_s.dup.force_encoding(Encoding::UTF_8)
+      return text.gsub(KEY_PADDING, "") if text.valid_encoding?
+
+      # Not UTF-8: a plain strip, and the character check refuses it.
+      value.to_s.b.strip
+    end
+
     def http_get(uri)
       http = Net::HTTP.new(uri.host, uri.port)
       http.use_ssl = uri.scheme == "https"
@@ -155,6 +195,15 @@ module ZeroDrop
       http.request(req)
     end
 
+    # The server explains a 401 in its JSON body; pass that on.
+    def error_detail(res)
+      body = JSON.parse(res.body.to_s)
+      detail = body["error"] if body.is_a?(Hash)
+      detail.is_a?(String) ? detail : nil
+    rescue JSON::ParserError, TypeError
+      nil
+    end
+
     def build_email(raw)
       Email.new(
         id: raw["id"],

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zerodrop
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - ZeroDrop
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-13 00:00:00.000000000 Z
+date: 2026-10-19 00:00:00.000000000 Z
 dependencies: []
 description: ZeroDrop catches verification emails at Cloudflare's edge and auto-extracts
   OTP codes and magic links. Test email verification, magic links, OTP and password