uri-smtp 0.7.3 → 0.7.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 32bf646636db9537ce1c5a5a044f9d467a9e231c0a43f59fe5e109e9866716f8
-  data.tar.gz: 76781018aa0ac3b6b8567b3547cae5350ac2611272154d7fb7dce22dd3859cde
+  metadata.gz: 9a91cda84c048c652dc1da97c080fa6df16320d6c6fbac55563413f2b73b07e3
+  data.tar.gz: 984ec2c5976e7e3b8bf51de646961769c9c89df20b1a76c29cc5885cab3cb1d9
 SHA512:
-  metadata.gz: d94721883773f26c4edeb39fbc884d4a78dd601877d7e6ba0f2ead74c2876e8ebac21f5637a1012dc9cde9bba5ca679bf01c1e7e3f954f6d05b56dde0d92a2ef
-  data.tar.gz: 7d68939c2782f247335486f4fa918ad7f96a79c3cb8d3853355bac5dd8221b906a0a664be0eaefa6117c79e9d317ca78c5461255a9f33a60457ac38a568bd76f
+  metadata.gz: ab85f5367934a7b56e1b9899c5addbdf27f9cd2774b8e9593cf4a24b6f3afcbfa7920d3c887e1afe32d8e22e75a4954c1aaeb9cb8b9b5041ba6499509b93d84d
+  data.tar.gz: 0b3d5d09a8247d7113908eb355da91106fb384f4743fce4d40429bc5f0081d88be8532ed7bcaefa4b9d271746c269761833f2debcf35aa2573a5a8f2dafb58b3

data/CHANGELOG.md

@@ -7,16 +7,25 @@ Changes can be:
 
 ## [Unreleased]
 
-## v0.7.3
+- ✨ `smtps+insecure://`  
+  TLS, skipping certificate verification.
+  Adds `#tls_verify`; `to_h` emits `tls_verify: false` (default format) / `openssl_verify_mode: "none"` (`:am` format).
+- ✨ `to_h` accepts `user:`/`password:` overrides
+  provide credentials separately (no uri-escaping) and `auth` still resolves from the scheme, e.g.
+  ```ruby
+  URI("smtps+login://smtp.gmail.com").to_h(format: :am, user: ENV["U"], password: ENV["P"])
+  ```
+
+## [v0.7.3](https://github.com/eval/uri-smtp/releases/tag/v0.7.3)
 
 - 🛡️ MFA required to publish this gem
 
-## [0.7.x] - 2025-07-28
+## [v0.7.2](https://github.com/eval/uri-smtp/releases/tag/v0.7.2)
 
 - 🛡️ Push and sign gem via GH Actions (i.e. trusted publisher)  
   See "Provenance" at https://rubygems.org/gems/uri-smtp
 
-## [0.6.0] - 2025-07-27
+## [v0.6.0](https://github.com/eval/uri-smtp/releases/tag/v0.6.0)
 
 - ✨ API-docs at https://eval.github.io/uri-smtp/  
 - 🐛 "smtp+insecure+foo://..." not considered `#insecure?`  
@@ -24,7 +33,7 @@ Changes can be:
 - 🐛 "smtp+insecure://..." having auth "insecure"  
 - ⚠️ remove `#starttls?`  
 
-## [0.5.0] - 2025-07-25
+## [v0.5.0](https://github.com/eval/uri-smtp/releases/tag/v0.5.0)
 
 - Add: `uri#read_timeout`, `uri#open_timeout`  
   Coerced integers from query:
@@ -41,15 +50,15 @@ Changes can be:
   NOTE Any domain from the query takes precedence.
 - Fix: "smtps+foo://..." having no tls
 
-## [0.4.0] - 2025-07-23
+## [v0.4.0](https://github.com/eval/uri-smtp/releases/tag/v0.4.0)
 
 - FIX: correct settings for action_mailer using mail v2.8.1
 
-## [0.3.0] - 2025-07-23
+## [v0.3.0](https://github.com/eval/uri-smtp/releases/tag/v0.3.0)
 
 - FIX: Kernel.URI should accept URI's
 
-## [0.2.0] - 2025-07-18
+## [v0.2.0](https://github.com/eval/uri-smtp/releases/tag/v0.2.0)
 
 - Feature complete
 

data/README.md

@@ -76,7 +76,7 @@ URI("smtps+login://user%40gmail.com:p%40ss@smtp.gmail.com?domain=sender.org").to
 
 For [ActionMailer configuration](https://guides.rubyonrails.org/action_mailer_basics.html#action-mailer-configuration), use `format: :action_mailer` (or `:am`):
 ```ruby
-URI("smtps+login://user%40gmail.com:p%40ss@smtp.gmail.com?domain=sender.org").to_h(format: :am)
+URI("smtps+login://user%40gmail.com:p%40ss@smtp.gmail.com#sender.org").to_h(format: :am)
 #=>
 {address: "smtp.gmail.com",
  authentication: "login",
@@ -92,11 +92,32 @@ Besides renaming some keys, this also works around a quirk in `v2.8.1` of the ma
 
 Full Rails config:
 ```ruby
+    # config/environments/development.rb
     config.action_mailer.delivery_method = :smtp
     # [mailcatcher](https://github.com/sj26/mailcatcher) fallback:
     config.action_mailer.smtp_settings = URI(ENV.fetch("SMTP_URL", "smtp://127.0.0.1:1025")).to_h(format: :am)
 ```
 
+#### Credentials separately
+
+Credentials in the URL must be uri-escaped (e.g. `user@gmail.com` → `user%40gmail.com`), which is easy to get wrong and makes the (env-var) value hard to read. To avoid this, leave them out of the URL and pass them to `to_h` instead:
+
+```ruby
+config.action_mailer.smtp_settings =
+  URI("smtps+login://smtp.gmail.com#sender.org")
+    .to_h(format: :am, user: ENV["SMTP_USERNAME"], password: ENV["SMTP_PASSWORD"])
+#=>
+{address: "smtp.gmail.com",
+ authentication: "login",
+ domain: "sender.org",
+ port: 465,
+ tls: true,
+ user_name: "...",
+ password: "..."}
+```
+
+The URL carries the connection shape; the env-vars carry the secrets. Note `auth` still resolves from the scheme (`+login`) even though the URL has no userinfo, and the overrides take precedence over any credentials in the URL.
+
 ## SMTP-URI
 
 There's no official specification for SMTP-URIs. There's some prior work though. This implementation is heavily inspired by [aerc](https://git.sr.ht/~rjarry/aerc/tree/master/item/doc/aerc-smtp.5.scd).  
@@ -111,6 +132,8 @@ There's no official specification for SMTP-URIs. There's some prior work though.
   SMTP without STARTTLS (i.e. `url.starttls #=> false`)..
 - `smtps`  
   SMTP with TLS.
+- `smtps+insecure`  
+  SMTP with TLS, skipping certificate verification (i.e. `url.tls_verify #=> false`).
 
 > [!NOTE]
 > to get `url.starttls #=> :auto`, provide it in the query: `smtp://user:pw@foo?auth=auto`. In that case `net-smtp` uses STARTTLS when the server supports it (but won't halt like when using `:always`).
@@ -141,6 +164,7 @@ Any value for auth that passes the URI-parser is acceptable. Though the followin
 | `smtp+login://user:pass@mail.example.com` | ❌ | 587 | ⚡ | login | STARTTLS `:always` with LOGIN auth |
 | `smtp+none://mail.example.com` | ❌ | 587 | 🔄 | none | Explicit no authentication |
 | `smtps://mail.example.com` | ✅ | 465 | ❌ | none | Direct TLS connection |
+| `smtps+insecure://mail.example.com` | ✅ | 465 | ❌ | none | Direct TLS, skipping certificate verification |
 | `smtps://mail.example.com?domain=sender.org&read_timeout=5&open_timeout=5` | ✅ | 465 | ❌ | none | `domain`, `read_timeout` and `open_timeout` set |
 | `smtps+login://user@imap.gmail.com` | ✅ | 465 | ❌ | login | Direct TLS with LOGIN auth |
 | `smtps://user%40gmail.com:p%40ss@imap.gmail.com` | ✅ | 465 | ❌ | login | Direct TLS with encoded userinfo `user@gmail.com:p@ss` |
@@ -164,7 +188,28 @@ Any value for auth that passes the URI-parser is acceptable. Though the followin
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 Use `bin/yard server --reload` when working on documentation.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bin/rake install`.
+
+### Releasing
+
+The gem is published automatically by GitHub Actions ([`.github/workflows/release.yml`](.github/workflows/release.yml)) when a `v*` tag is pushed: CI builds the gem, publishes it to [rubygems.org](https://rubygems.org) as a [trusted publisher](https://guides.rubygems.org/trusted-publishing/) (with build provenance), and creates the GitHub release. **The gem is never pushed from your machine**, and CI never writes back to the repo.
+
+To cut a release:
+
+1. Bump the version:
+   ```sh
+   bin/rake 'gem:write_version[0.7.3]'
+   ```
+   This rewrites `lib/uri/smtp/version.rb` and updates `Gemfile.lock`.
+2. Finalize `CHANGELOG.md` (rename `## [Unreleased]` to the new version + date).
+3. Commit and push, then confirm CI is green.
+4. Build, tag and push:
+   ```sh
+   bin/rake release
+   ```
+   This builds the gem locally (verifying it builds), creates the `v0.7.3` tag, and pushes it to `origin` — which triggers the release workflow. Pushing to rubygems is disabled via `gem_push=no` (set in `mise.toml`); outside mise, run `gem_push=no bin/rake release`.
+
+Tags use a `v` prefix; a fourth version segment (e.g. `v0.7.3.rc1`) is published as a pre-release.
 
 ## Contributing
 

data/lib/uri/smtp/version.rb

@@ -4,6 +4,6 @@ require "uri"
 
 module URI
   class SMTP < URI::Generic
-    VERSION = "0.7.3"
+    VERSION = "0.7.4"
   end
 end

data/lib/uri/smtp.rb

@@ -45,14 +45,7 @@ module URI
     # @return [String] 'auth via scheme' when present, e.g. `"smtp+login://foo.org"`.
     # @return [String] else `"plain"`
     def auth
-      # net-smtp: passing authtype without user/pw raises error
-      return nil unless userinfo
-      return nil if parsed_query["auth"] == "none"
-      return parsed_query["auth"] if parsed_query.has_key?("auth")
-      return nil if scheme_auth == "none"
-      return scheme_auth if scheme_auth
-
-      "plain"
+      auth_for(credentials: !userinfo.nil?)
     end
 
     # Decoded userinfo formatted as String, Array or Hash.
@@ -142,20 +135,41 @@ module URI
     end
     alias_method :tls?, :tls
 
-    # Whether or not the scheme indicates to skip STARTTLS.
+    # Whether or not the scheme carries the `insecure` modifier.
+    #
+    # `insecure` relaxes the transport's security: with plaintext `smtp` it skips
+    # `STARTTLS` (see {#starttls}); with `smtps` it skips TLS certificate
+    # verification (see {#tls_verify}).
     #
     # @see #starttls
+    # @see #tls_verify
     #
     # @example
     #   URI("smtp+insecure://foo.org").insecure? #=> true
-    #   # This is equivalent (though shorter and more descriptive) to
+    #   # `smtp+insecure` is equivalent (though shorter and more descriptive) to
     #   URI("smtp://foo.org?starttls=false")
     #
+    #   # TLS without certificate verification
+    #   URI("smtps+insecure://foo.org").insecure? #=> true
+    #
     #   # combine with authentication
     #   URI("smtp+insecure+login://user:pw@foo.org").insecure? #=> true
-    # @return [Boolean] whether `scheme` starts with `"smtp+insecure"`.
+    # @return [Boolean] whether `scheme` includes the `insecure` modifier.
     def insecure?
-      scheme.start_with?("smtp+insecure")
+      scheme.split("+").include?("insecure")
+    end
+
+    # Whether or not to verify the server's TLS certificate.
+    #
+    # @see #insecure?
+    #
+    # @example
+    #   URI("smtps://foo.org").tls_verify          #=> true
+    #   URI("smtps+insecure://foo.org").tls_verify #=> false
+    # @return [false] when the scheme combines TLS with `insecure`, e.g. `smtps+insecure://`.
+    # @return [true] otherwise.
+    def tls_verify
+      !(tls? && insecure?)
     end
 
     # Whether or not `host` is considered local.
@@ -221,25 +235,44 @@ module URI
     #   # file: config/environments/development.rb
     #   # Config via env-var SMTP_URL or fallback to mailcatcher.
     #   config.action_mailer.smtp_settings = URI(ENV.fetch("SMTP_URL", "http://127.0.0.1:1025")).to_h(format: :am)
+    # @example provide credentials separately
+    #   # Avoids uri-escaping secrets in the URL, and still sets `authentication`
+    #   # from the scheme even though the URL has no userinfo.
+    #   URI("smtps+login://smtp.gmail.com#sender.org").to_h(format: :am, user: "user@gmail.com", password: "p@ss")
+    #   # =>
+    #   # {address: "smtp.gmail.com",
+    #   #  authentication: "login",
+    #   #  domain: "sender.org",
+    #   #  port: 465,
+    #   #  tls: true,
+    #   #  user_name: "user@gmail.com",
+    #   #  password: "p@ss"}
     # @param format [Symbol] the format type, `nil` (default), `:action_mailer`/`:am`.
+    # @param user [String, nil] override the user; takes precedence over any user in the URL. When given, `auth` resolves even without userinfo in the URL.
+    # @param password [String, nil] override the password; takes precedence over any password in the URL.
     # @return [Hash]
-    def to_h(format: nil)
+    def to_h(format: nil, user: nil, password: nil)
+      authentication = auth_for(credentials: !user.nil? || !password.nil? || !userinfo.nil?)
+      user ||= decoded_user
+      password ||= decoded_password
+
       case format
       when :am, :action_mailer
         {
           address: host,
-          authentication: auth,
+          authentication:,
           domain:,
           enable_starttls: starttls == :always,
           enable_starttls_auto: starttls == :auto,
           open_timeout:,
+          openssl_verify_mode: ("none" unless tls_verify),
           port:,
           read_timeout:,
           tls:
         }.tap do
           unless _1[:authentication].nil?
-            _1[:user_name] = decoded_user
-            _1[:password] = decoded_password
+            _1[:user_name] = user
+            _1[:password] = password
           end
           # mail 2.8.1 logic is faulty in that it shortcuts
           # (start)tls-settings when they are false.
@@ -252,7 +285,7 @@ module URI
         end.delete_if { |_k, v| v.nil? }
       else
         {
-          auth:,
+          auth: authentication,
           domain:,
           host:,
           open_timeout:,
@@ -260,11 +293,12 @@ module URI
           read_timeout:,
           scheme:,
           starttls:,
-          tls:
+          tls:,
+          tls_verify: (false unless tls_verify)
         }.tap do
           unless _1[:auth].nil?
-            _1[:user] = decoded_user
-            _1[:password] = decoded_password
+            _1[:user] = user
+            _1[:password] = password
           end
         end.delete_if { |_k, v| v.nil? }
       end
@@ -281,6 +315,19 @@ module URI
 
     private
 
+    # Resolve the authentication mechanism given whether credentials are
+    # available — either from `userinfo` in the URL or from `#to_h` overrides.
+    # net-smtp: passing authtype without user/pw raises an error, hence the guard.
+    def auth_for(credentials:)
+      return nil unless credentials
+      return nil if parsed_query["auth"] == "none"
+      return parsed_query["auth"] if parsed_query.has_key?("auth")
+      return nil if scheme_auth == "none"
+      return scheme_auth if scheme_auth
+
+      "plain"
+    end
+
     def scheme_auth
       string_absense_in(scheme.split("+").last, %w[smtp smtps insecure])
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: uri-smtp
 version: !ruby/object:Gem::Version
-  version: 0.7.3
+  version: 0.7.4
 platform: ruby
 authors:
 - Gert Goet