naijacloud-email 0.3.0

data/SECURITY.md

@@ -0,0 +1,92 @@
+# Security
+
+## Reporting a vulnerability
+
+Email **security@naijacloud.com**. Please do not open a public issue, and do not
+post a proof of concept anywhere public before we have shipped a fix.
+
+Include what you did, what happened, and the version of the gem. We acknowledge
+within two business days (West Africa Time) and will tell you what we intend to
+do and by when.
+
+If you have found a **leaked Naijamail key** — in a repository, a log, a
+screenshot — treat it as an incident and mail the same address. Revoke it from
+the dashboard first: revocation is immediate.
+
+## What this gem does with your key
+
+The API key is a sending credential. A leaked one is a phishing incident on a
+domain your customers trust, not an information disclosure, so the gem is built
+to keep it in exactly one place.
+
+1. **The key travels only in the `Authorization` header, over TLS.** It is never
+   put in a query string, a log line, the User-Agent, or an exception message.
+2. **HTTPS is enforced at construction.** A `base_url` whose scheme is not
+   `https` is refused unless the host is `localhost`, `127.0.0.1` or `::1`, for
+   development against a local control plane. `verify_mode` is set explicitly to
+   `OpenSSL::SSL::VERIFY_PEER` rather than inherited from whatever else in the
+   process has touched OpenSSL's defaults.
+3. **Redirects are never followed.** `net/http` does not follow them on its own,
+   and this gem additionally turns any 3xx into a hard `ServerError`. A followed
+   redirect re-sends the `Authorization` header to whatever host the response
+   names — that is how bearer tokens leak.
+4. **The key is redacted everywhere it could be printed.** `Client#inspect` and
+   `Client#to_s` show `nmail_live_***`. The client does not keep the key as one
+   of its own instance variables — it is handed to the transport, whose `inspect`
+   is redacted too — so an error reporter that dumps the receiver's instance
+   variables finds nothing. `Marshal.dump` on a client raises rather than writing
+   a credential into a file nobody realises is a secret.
+5. **There is no verbose or debug mode.** `Net::HTTP#set_debug_output` writes
+   every header, `Authorization` included, to whatever IO it is given. The gem
+   never calls it and offers no switch that would.
+6. **Nothing is global.** Key, base URL and HTTP state live on the client
+   instance, so two clients holding two teams' keys cannot interfere.
+
+## What the gem refuses before a request leaves your process
+
+- **Header injection**: `\r`, `\n` or NUL anywhere in `from`, any address in
+  `to`/`cc`/`bcc`/`reply_to`, `subject`, a custom header name or value, an
+  attachment filename, the idempotency key or the User-Agent suffix. Message
+  bodies are exempt: they are content, not headers.
+- **Forbidden custom headers**: `From`, `To`, `Cc`, `Bcc`, `Subject`,
+  `DKIM-Signature`, `Received`, case-insensitively. Overriding one would sidestep
+  the domain authorisation the From address is checked against.
+- **Limits**: 50 recipients across to/cc/bcc, 25 custom headers, 10 tags, 10 MiB
+  encoded payload.
+- **File paths in attachments.** `content:` takes bytes. The gem never opens a
+  path, because an SDK that opens whatever path it is handed is a
+  local-file-disclosure primitive in a web handler.
+- **Message ids** that could alter the request path.
+- **Keys of the wrong shape**, so an empty or truncated key fails on your machine
+  rather than as a 401 in production an hour after deploy.
+
+## Webhook verification
+
+`Webhooks.verify` compares signatures with `OpenSSL.secure_compare` where it
+exists (Ruby 3.0+) and a constant-time XOR comparison otherwise — never `==`,
+which stops at the first differing byte and leaks how much of a guess was right.
+
+It signs and verifies the **raw request body**. It refuses a parsed Hash, because
+re-serializing produces different bytes than the ones that were signed. The
+timestamp is part of the signed payload and is checked against a 300-second
+default tolerance, which is what stops a captured delivery being replayed. A
+failed verification never returns the expected signature: that would hand an
+attacker the answer.
+
+## Supply chain
+
+The gem has **zero runtime dependencies**. Everything is standard library:
+`net/http`, `uri`, `json`, `openssl`, `securerandom`, `time`, `base64`.
+
+That is a deliberate cost. This package is installed into processes that hold
+live sending keys, so every third-party runtime dependency would be another
+maintainer whose account compromise becomes our customers' incident. A faster
+HTTP client is not worth that trade. Development and test dependencies (minitest,
+rake) are not shipped to users.
+
+Releases require MFA on the RubyGems account (`rubygems_mfa_required`).
+
+## Supported versions
+
+Security fixes are released for the latest minor version. Ruby 2.7 and newer are
+supported.

data/lib/naijacloud/email/client.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module NaijaCloud
+  module Email
+    # The entry point.
+    #
+    #   nm = NaijaCloud::Email::Client.new          # reads NAIJAMAIL_API_KEY
+    #   nm.emails.send_email(from: ..., to: ..., subject: ..., html: ...)
+    #
+    # Everything a request needs -- key, base URL, timeouts, HTTP object -- hangs
+    # off the instance. No class-level configuration, no singleton: two clients
+    # holding two different teams' keys have to be able to run in one process
+    # without one quietly borrowing the other's credential.
+    class Client
+      DEFAULT_BASE_URL = "https://api.naijacloud.com"
+
+      API_KEY_ENV  = "NAIJAMAIL_API_KEY"
+      BASE_URL_ENV = "NAIJAMAIL_BASE_URL"
+
+      # The shape the control plane mints (MAIL_KEY_PREFIX_LIVE / _TEST plus 24
+      # random bytes, base64url). Checked at construction so an empty string or a
+      # truncated copy-paste fails here, on the developer's machine, rather than
+      # as a 401 in production an hour after deploy.
+      #
+      # A test key is accepted by the constructor and refused by the send path
+      # with 403 -- that refusal is the server's job and is deliberate, so this
+      # SDK must not pre-empt it.
+      #
+      # Two families, because the API accepts two: `nmail_live_`/`nmail_test_`
+      # is a Naijamail-only key from the Email screen, and `nc_live_` is a
+      # workspace API key carrying the Email send scope, from Settings -> API
+      # keys. It stays an allowlist rather than relaxing to "any non-empty
+      # string": the check exists to catch the truncated paste and the
+      # wrong-variable-name deploy, and a pattern that accepts anything catches
+      # neither.
+      KEY_PATTERN = /\A(?:nmail_(?:live|test)|nc_live)_[A-Za-z0-9_-]{8,}\z/.freeze
+
+      # The only hosts allowed to be plaintext, for a developer running the
+      # control plane locally. Everything else must be https: a bearer key that
+      # can mail as a customer's verified domain has no business on the wire in
+      # clear, and "it was only staging" is how it gets there.
+      LOCAL_HOSTS = ["localhost", "127.0.0.1", "::1"].freeze
+
+      # More retries than this only stretches an outage into a hang: with the
+      # 8s backoff cap and a 30s per-attempt deadline, ten retries is already
+      # minutes of a caller blocked on one send.
+      MAX_RETRIES_LIMIT = 10
+
+      # The platform's pre-scope personal access token. The API refuses it on the
+      # mail routes; saying so here beats "not shaped like a key" (it is a real
+      # NaijaCloud credential, just the wrong kind). Wording fixed by SDK
+      # contract section 1, identical in all five SDKs.
+      PAT_PREFIX  = "nc_pat_"
+      PAT_MESSAGE = "this is a personal access token (nc_pat_…), which cannot send mail; " \
+                    "use a mail API key (nmail_live_… or nmail_test_…) or a workspace API key " \
+                    "with the Email send scope (nc_live_…)"
+
+      attr_reader :base_url, :timeout, :max_retries, :user_agent
+
+      def initialize(api_key: nil, base_url: nil, timeout: 30, max_retries: 2, user_agent_suffix: nil)
+        key          = resolve_api_key(api_key)
+        @base_uri    = resolve_base_url(base_url)
+        @base_url    = @base_uri.to_s
+        @timeout     = validate_timeout(timeout)
+        @max_retries = validate_max_retries(max_retries)
+        @user_agent  = build_user_agent(user_agent_suffix)
+
+        # The key is deliberately NOT kept as an instance variable of the client:
+        # it is handed to the transport, which is the only object that needs it,
+        # and the local goes out of scope here. Anything that walks a client's
+        # instance variables -- an error reporter serializing the receiver, a
+        # console session, a naive deep-inspect in a test failure -- then has
+        # nothing to find, because the transport redacts its own inspect too.
+        @key_display = NaijaCloud::Email.redact_key(key)
+
+        @http = Transport.new(
+          api_key: key,
+          base_url: @base_uri,
+          timeout: @timeout,
+          max_retries: @max_retries,
+          user_agent: @user_agent,
+        )
+
+        @emails = Emails.new(@http)
+      end
+
+      # The one resource. Two endpoints, because the server has two.
+      attr_reader :emails
+
+      # Both overridden, and neither mentions @api_key.
+      #
+      # This is not decoration. An unhandled exception prints the receiver's
+      # inspect, `p client` in a console prints it, a JSON logger calling to_s on
+      # its context prints it, and any of those is a live sending credential in a
+      # log aggregator that a much wider group of people can read than should
+      # ever see it. The default Object#inspect would print every instance
+      # variable, and the transport's key with it.
+      def inspect
+        "#<NaijaCloud::Email::Client base_url=#{@base_url} api_key=#{@key_display} " \
+          "timeout=#{@timeout} max_retries=#{@max_retries}>"
+      end
+      alias to_s inspect
+
+      # Marshal/YAML dumps of a client would carry the key into whatever wrote
+      # them. There is no reason to serialize a client, so refuse rather than
+      # produce a file nobody realises is a secret.
+      def marshal_dump
+        raise Error.new("a NaijaCloud::Email::Client holds an API key and must not be serialized")
+      end
+
+      # Psych does not use marshal_dump: it walks instance variables, down
+      # @http to the key. encode_with is the hook it does call.
+      def encode_with(_coder)
+        raise Error.new("a NaijaCloud::Email::Client holds an API key and must not be serialized")
+      end
+
+      private
+
+      def resolve_api_key(api_key)
+        # ENV values pick up a trailing newline surprisingly often (`export
+        # KEY=$(cat key.txt)`), and a newline in a header value is a header
+        # injection, so strip before validating rather than after.
+        key = api_key.nil? ? ENV[API_KEY_ENV] : api_key
+        key = key.strip if key.is_a?(String)
+
+        if key.nil? || key.empty?
+          raise ValidationError.new(
+            "no API key. Pass api_key: to the constructor or set #{API_KEY_ENV} in the environment.",
+          )
+        end
+        raise ValidationError.new(PAT_MESSAGE) if key.is_a?(String) && key.start_with?(PAT_PREFIX)
+
+        unless key.is_a?(String) && key =~ KEY_PATTERN
+          # The key itself is never echoed, not even a "got: ..." fragment: this
+          # message goes straight into a log on a failed boot.
+          raise ValidationError.new(
+            "API key does not look like a Naijamail key " \
+            "(expected nmail_live_..., nmail_test_... or nc_live_...)",
+          )
+        end
+
+        key
+      end
+
+      def resolve_base_url(base_url)
+        # A blank NAIJAMAIL_BASE_URL (an empty `export` in a deploy config) means
+        # "not set", not "invalid": the default applies, as in every other SDK.
+        env = ENV[BASE_URL_ENV]
+        env = nil if env.nil? || env.strip.empty?
+
+        raw = base_url || env || DEFAULT_BASE_URL
+        raw = raw.to_s.strip
+
+        uri =
+          begin
+            URI.parse(raw)
+          rescue URI::InvalidURIError => e
+            raise ValidationError.new("base_url is not a valid URL: #{e.message}")
+          end
+
+        unless uri.is_a?(URI::HTTP) && uri.host && !uri.host.empty?
+          raise ValidationError.new("base_url must be an absolute http(s) URL, got #{raw.inspect}")
+        end
+
+        # A query or fragment would sit after every path this client appends, so
+        # the request would go somewhere other than where the caller thinks.
+        # Refused rather than stripped: silently dropping part of a configured
+        # URL hides a configuration mistake.
+        if uri.query || uri.fragment
+          raise ValidationError.new("base_url must not contain a query string or a fragment")
+        end
+
+        # URI#host keeps the brackets on an IPv6 literal ("[::1]"); #hostname
+        # strips them.
+        host = uri.hostname.downcase
+
+        if uri.scheme != "https" && !LOCAL_HOSTS.include?(host)
+          raise ValidationError.new(
+            "base_url must use https (got #{uri.scheme.inspect} for host #{host.inspect}). " \
+            "Plaintext is allowed only for localhost, 127.0.0.1 and ::1.",
+          )
+        end
+
+        uri
+      end
+
+      def validate_timeout(timeout)
+        unless timeout.is_a?(Numeric) && timeout.to_f > 0
+          raise ValidationError.new("timeout must be a positive number of seconds")
+        end
+
+        timeout.to_f
+      end
+
+      def validate_max_retries(max_retries)
+        unless max_retries.is_a?(Integer) && max_retries >= 0 && max_retries <= MAX_RETRIES_LIMIT
+          raise ValidationError.new("max_retries must be an Integer from 0 to #{MAX_RETRIES_LIMIT}")
+        end
+
+        max_retries
+      end
+
+      # Identifies the SDK in our logs, which is how we tell an SDK bug from a
+      # customer's hand-rolled client. The suffix is checked for CR/LF for the
+      # same reason every other header value is: it ends up in one.
+      def build_user_agent(suffix)
+        agent = "nc-email-ruby/#{VERSION} (ruby/#{RUBY_VERSION})"
+        return agent if suffix.nil?
+
+        unless suffix.is_a?(String)
+          raise ValidationError.new("user_agent_suffix must be a string")
+        end
+        if suffix =~ /[\r\n\0]/
+          raise ValidationError.new("user_agent_suffix contains a line break or NUL")
+        end
+
+        suffix = suffix.strip
+        suffix.empty? ? agent : "#{agent} #{suffix}"
+      end
+    end
+  end
+end