sanitize_email 2.0.3 → 2.0.5
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- checksums.yaml.gz.sig +0 -0
- data/CHANGELOG.md +97 -12
- data/CODE_OF_CONDUCT.md +84 -0
- data/CONTRIBUTING.md +47 -0
- data/{LICENSE → LICENSE.txt} +1 -1
- data/README.md +415 -59
- data/SECURITY.md +15 -0
- data/lib/sanitize_email/bleach.rb +75 -68
- data/lib/sanitize_email/config.rb +22 -22
- data/lib/sanitize_email/deprecation.rb +6 -6
- data/lib/sanitize_email/{engine.rb → engine_v5.rb} +4 -3
- data/lib/sanitize_email/engine_v6.rb +15 -0
- data/lib/sanitize_email/mail_ext.rb +2 -0
- data/lib/sanitize_email/mail_header_tools.rb +24 -16
- data/lib/sanitize_email/overridden_addresses.rb +84 -22
- data/lib/sanitize_email/railtie.rb +1 -1
- data/lib/sanitize_email/rspec_matchers.rb +66 -31
- data/lib/sanitize_email/test_helpers.rb +6 -6
- data/lib/sanitize_email/version.rb +4 -2
- data/lib/sanitize_email.rb +35 -19
- data.tar.gz.sig +0 -0
- metadata +108 -93
- metadata.gz.sig +0 -0
- data/.coveralls.yml +0 -1
- data/.gitignore +0 -12
- data/.pryrc +0 -11
- data/.reek +0 -9
- data/.rspec +0 -2
- data/.rubocop.yml +0 -73
- data/.rubocop_rspec.yml +0 -35
- data/.rubocop_todo.yml +0 -21
- data/.ruby-gemset +0 -1
- data/.ruby-version +0 -1
- data/.travis.yml +0 -71
- data/Appraisals +0 -29
- data/Gemfile +0 -22
- data/REEK +0 -2
- data/Rakefile +0 -52
- data/gemfiles/rails_4_2.gemfile +0 -17
- data/gemfiles/rails_5_0.gemfile +0 -17
- data/gemfiles/rails_5_1.gemfile +0 -17
- data/gemfiles/rails_5_2.gemfile +0 -17
- data/init.rb +0 -3
- data/sanitize_email.gemspec +0 -49
- data/spec/sanitize_email_spec.rb +0 -944
- data/spec/spec_helper.rb +0 -28
data/README.md
CHANGED
|
@@ -1,23 +1,227 @@
|
|
|
1
1
|
# sanitize_email
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
3
|
+
<div id="badges">
|
|
4
|
+
|
|
5
|
+
[![CI Build][🚎dl-cwfi]][🚎dl-cwf]
|
|
6
|
+
[![Test Coverage][🔑cc-covi]][🔑cc-cov]
|
|
7
|
+
[![Maintainability][🔑cc-mnti]][🔑cc-mnt]
|
|
8
|
+
[![Depfu][🔑depfui]][🔑depfu]
|
|
9
|
+
|
|
10
|
+
[🚎dl-cwf]: https://github.com/pboling/sanitize_email/actions/workflows/supported.yml
|
|
11
|
+
[🚎dl-cwfi]: https://github.com/pboling/sanitize_email/actions/workflows/supported.yml/badge.svg
|
|
12
|
+
|
|
13
|
+
[comment]: <> ( 🔑 KEYED LINKS )
|
|
14
|
+
|
|
15
|
+
[🔑cc-mnt]: https://codeclimate.com/github/pboling/sanitize_email/maintainability
|
|
16
|
+
[🔑cc-mnti]: https://api.codeclimate.com/v1/badges/65af4948d859903a0372/maintainability
|
|
17
|
+
[🔑cc-cov]: https://codeclimate.com/github/pboling/sanitize_email/test_coverage
|
|
18
|
+
[🔑cc-covi]: https://api.codeclimate.com/v1/badges/65af4948d859903a0372/test_coverage
|
|
19
|
+
[🔑depfu]: https://depfu.com/github/pboling/sanitize_email
|
|
20
|
+
[🔑depfui]: https://badges.depfu.com/badges/bba430e8f19a2ba3273fb20d5e8c82d6/count.svg
|
|
21
|
+
|
|
22
|
+
-----
|
|
23
|
+
|
|
24
|
+
[![Liberapay Patrons][⛳liberapay-img]][⛳liberapay]
|
|
25
|
+
[![Sponsor Me on Github][🖇sponsor-img]][🖇sponsor]
|
|
26
|
+
<span class="badge-buymeacoffee">
|
|
27
|
+
<a href="https://ko-fi.com/O5O86SNP4" target='_blank' title="Donate to my FLOSS or refugee efforts at ko-fi.com"><img src="https://img.shields.io/badge/buy%20me%20coffee-donate-yellow.svg" alt="Buy me coffee donation button" /></a>
|
|
28
|
+
</span>
|
|
29
|
+
<span class="badge-patreon">
|
|
30
|
+
<a href="https://patreon.com/galtzo" title="Donate to my FLOSS or refugee efforts using Patreon"><img src="https://img.shields.io/badge/patreon-donate-yellow.svg" alt="Patreon donate button" /></a>
|
|
31
|
+
</span>
|
|
32
|
+
|
|
33
|
+
</div>
|
|
34
|
+
|
|
35
|
+
[⛳liberapay-img]: https://img.shields.io/liberapay/patrons/pboling.svg?logo=liberapay
|
|
36
|
+
[⛳liberapay]: https://liberapay.com/pboling/donate
|
|
37
|
+
[🖇sponsor-img]: https://img.shields.io/badge/Sponsor_Me!-pboling.svg?style=social&logo=github
|
|
38
|
+
[🖇sponsor]: https://github.com/sponsors/pboling
|
|
39
|
+
|
|
40
|
+
This gem allows you to override your mail delivery settings, globally or in a local context.
|
|
41
|
+
It is like a Ruby encrusted condom for your email server,
|
|
42
|
+
just in case it decides to have intercourse with other servers via sundry mail protocols.
|
|
43
|
+
|
|
44
|
+
Seriously though, this gem solves similar problems as the excellent [`mailcatcher`](https://mailcatcher.me/) gem,
|
|
45
|
+
and mailcatcher solves those problems far more easily.
|
|
46
|
+
|
|
47
|
+
In addition, this gem solves problems that mailcatcher does not solve. I recommend using both!
|
|
48
|
+
|
|
49
|
+
To make an analogy, `mailcatcher` is akin to `webmock`, entirely preventing interaction with your real live mail server,
|
|
50
|
+
while this gem allows you to effectively use your real live (production!) mail server, while
|
|
51
|
+
intercepting and modifying recipeients on the way out, so that testing emails go to safe locations.
|
|
52
|
+
|
|
53
|
+
It is a bit like using the "test" Visa credit card number `4701322211111234` with a real payment gateway.
|
|
54
|
+
|
|
55
|
+
## Encryption
|
|
56
|
+
|
|
57
|
+
Making special note of this use case because it is important for companies working on HIPAA-compliant products.
|
|
58
|
+
When you are sending emails through an encrypted email provider, e.g. [Paubox](https://www.paubox.com/),
|
|
59
|
+
testing your email in the aforementioned `mailcatcher` may not be enough.
|
|
60
|
+
|
|
61
|
+
If you want to test all the way through Paubox's system, but have the email go to a safe testing account address,
|
|
62
|
+
then this is the gem for you.
|
|
63
|
+
|
|
64
|
+
## Compatibility
|
|
65
|
+
|
|
66
|
+
⚙️ Compatible with all versions of Ruby >= 2.3.
|
|
67
|
+
⚙️ Compatible with all Ruby web Frameworks (Hanami, Roda, Sinatra, Rails).
|
|
68
|
+
⚙️ Compatible with all versions of Rails from 3.0 - 7.1+.
|
|
69
|
+
⚙️ Compatible with scripted usage of Mail gem outside a web framework.
|
|
70
|
+
⚙️ Compatible with [`sendgrid-actionmailer`](https://github.com/eddiezane/sendgrid-actionmailer)'s support for personalizations, and will override email addresses there according to the configuration.
|
|
71
|
+
⚙️ If this gem is not compatible with your use case, and you'd like it to be, I'd like to hear about it!
|
|
72
|
+
|
|
73
|
+
## 🛞 DVCS
|
|
74
|
+
|
|
75
|
+
This project does not trust any one version control system,
|
|
76
|
+
so it abides the principles of ["Distributed Version Control Systems"][💎d-in-dvcs]
|
|
77
|
+
|
|
78
|
+
Find this project on:
|
|
79
|
+
|
|
80
|
+
| Any | Of | These | DVCS |
|
|
81
|
+
|----------------|------------------|----------------|----------------|
|
|
82
|
+
| [🐙hub][🐙hub] | [🧊berg][🧊berg] | [🛖hut][🛖hut] | [🧪lab][🧪lab] |
|
|
83
|
+
|
|
84
|
+
[comment]: <> ( DVCS LINKS )
|
|
85
|
+
|
|
86
|
+
[💎d-in-dvcs]: https://railsbling.com/posts/dvcs/put_the_d_in_dvcs/
|
|
87
|
+
|
|
88
|
+
[🧊berg]: https://codeberg.org/pboling/sanitize_email
|
|
89
|
+
[🐙hub]: https://gitlab.com/pboling/sanitize_email
|
|
90
|
+
[🛖hut]: https://sr.ht/~galtzo/pboling/sanitize_email
|
|
91
|
+
[🧪lab]: https://gitlab.com/pboling/sanitize_email
|
|
92
|
+
|
|
93
|
+
<!--
|
|
94
|
+
Numbering rows and badges in each row as a visual "database" lookup,
|
|
95
|
+
as the table is extremely dense, and it can be very difficult to find anything
|
|
96
|
+
Putting one on each row here, to document the emoji that should be used, and for ease of copy/paste.
|
|
97
|
+
|
|
98
|
+
row #s:
|
|
99
|
+
1️⃣
|
|
100
|
+
2️⃣
|
|
101
|
+
3️⃣
|
|
102
|
+
4️⃣
|
|
103
|
+
5️⃣
|
|
104
|
+
6️⃣
|
|
105
|
+
7️⃣
|
|
106
|
+
|
|
107
|
+
badge #s:
|
|
108
|
+
⛳️
|
|
109
|
+
🖇
|
|
110
|
+
🏘
|
|
111
|
+
🚎
|
|
112
|
+
🖐
|
|
113
|
+
🧮
|
|
114
|
+
📗
|
|
115
|
+
|
|
116
|
+
appended indicators:
|
|
117
|
+
♻️ / 🔑 - Tagged URLs need to be updated from SAAS integration. Find / Replace is insufficient.
|
|
118
|
+
-->
|
|
119
|
+
|
|
120
|
+
| | Project | bundle add sanitize_email |
|
|
121
|
+
|:----|--------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
122
|
+
| 1️⃣ | name, license, docs, standards | [![RubyGems.org][⛳️name-img]][⛳️gem] [![License: MIT][🖇src-license-img]][🖇src-license] [![RubyDoc.info][🚎yard-img]][🚎yard] [][🚎yard] [![SemVer 2.0.0][🧮semver-img]][🧮semver] [![Keep-A-Changelog 1.0.0][📗keep-changelog-img]][📗keep-changelog] |
|
|
123
|
+
| 2️⃣ | version & activity | [![Gem Version][⛳️version-img]][⛳️gem] [![Total Downloads][🖇DL-total-img]][⛳️gem] [![Download Rank][🏘DL-rank-img]][⛳️gem] [![Source Code][🚎src-main-img]][🚎src-main] [![Open PRs][🖐prs-o-img]][🖐prs-o] [![Closed PRs][🧮prs-c-img]][🧮prs-c] |
|
|
124
|
+
| 3️⃣ | maintenance & linting | [![Maintainability][🔑cc-mnti]][🔑cc-mnt] [![Helpers][🖇triage-help-img]][🖇triage-help] [![Depfu][🔑depfui]][🔑depfu] [![Contributors][🚎contributors-img]][🚎contributors] [![Style][🖐style-wf-img]][🖐style-wf] |
|
|
125
|
+
| 4️⃣ | testing | [![Supported][🏘sup-wf-img]][🏘sup-wf] [![Heads][🚎heads-wf-img]][🚎heads-wf] |
|
|
126
|
+
| 5️⃣ | coverage & security | [![CodeClimate][🔑cc-covi]][🔑cc-cov] [![CodeCov][🖇codecov-img♻️]][🖇codecov] [![Coveralls][🏘coveralls-img]][🏘coveralls] [![Security Policy][🚎sec-pol-img]][🚎sec-pol] [![CodeQL][🖐codeQL-img]][🖐codeQL] [![Code Coverage][🧮cov-wf-img]][🧮cov-wf] |
|
|
127
|
+
| 6️⃣ | resources | [![Get help on Codementor][🖇codementor-img]][🖇codementor] [![Chat][🏘chat-img]][🏘chat] [![Blog][🚎blog-img]][🚎blog] [![Wiki][🖐wiki-img]][🖐wiki] |
|
|
128
|
+
| 7️⃣ | `...` 💖 | [![Liberapay Patrons][⛳liberapay-img]][⛳liberapay] [![Sponsor Me][🖇sponsor-img]][🖇sponsor] [![Follow Me on LinkedIn][🖇linkedin-img]][🖇linkedin] [![Find Me on WellFound:][✌️wellfound-img]][✌️wellfound] [![Find Me on CrunchBase][💲crunchbase-img]][💲crunchbase] [![My LinkTree][🌳linktree-img]][🌳linktree] [![Follow Me on Ruby.Social][🐘ruby-mast-img]][🐘ruby-mast] [![Follow Me on FLOSS.Social][🐘floss-mast-img]][🐘floss-mast] [![Follow Me on Mastodon.Social][🐘mast-img]][🐘mast] [![Tweet @ Peter][🐦tweet-img]][🐦tweet] [💻][coderme] [🌏][aboutme] |
|
|
129
|
+
|
|
130
|
+
<!--
|
|
131
|
+
The link tokens in the following sections should be kept ordered by the row and badge numbering scheme
|
|
132
|
+
-->
|
|
133
|
+
|
|
134
|
+
<!-- 1️⃣ name, license, docs -->
|
|
135
|
+
[⛳️gem]: https://rubygems.org/gems/sanitize_email
|
|
136
|
+
[⛳️name-img]: https://img.shields.io/badge/name-sanitize_email-brightgreen.svg?style=flat
|
|
137
|
+
[🖇src-license]: https://opensource.org/licenses/MIT
|
|
138
|
+
[🖇src-license-img]: https://img.shields.io/badge/License-MIT-green.svg
|
|
139
|
+
[🚎yard]: https://www.rubydoc.info/gems/sanitize_email
|
|
140
|
+
[🚎yard-img]: https://img.shields.io/badge/documentation-rubydoc-brightgreen.svg?style=flat
|
|
141
|
+
[🧮semver]: http://semver.org/
|
|
142
|
+
[🧮semver-img]: https://img.shields.io/badge/semver-2.0.0-FFDD67.svg?style=flat
|
|
143
|
+
[📗keep-changelog]: https://keepachangelog.com/en/1.0.0/
|
|
144
|
+
[📗keep-changelog-img]: https://img.shields.io/badge/keep--a--changelog-1.0.0-FFDD67.svg?style=flat
|
|
145
|
+
|
|
146
|
+
<!-- 2️⃣ version & activity -->
|
|
147
|
+
[⛳️version-img]: http://img.shields.io/gem/v/sanitize_email.svg
|
|
148
|
+
[🖇DL-total-img]: https://img.shields.io/gem/dt/sanitize_email.svg
|
|
149
|
+
[🏘DL-rank-img]: https://img.shields.io/gem/rt/sanitize_email.svg
|
|
150
|
+
[🚎src-main]: https://gitlab.com/pboling/sanitize_email
|
|
151
|
+
[🚎src-main-img]: https://img.shields.io/badge/source-gitlab-brightgreen.svg?style=flat
|
|
152
|
+
[🖐prs-o]: https://gitlab.com/pboling/sanitize_email/-/merge_requests
|
|
153
|
+
[🖐prs-o-img]: https://img.shields.io/github/issues-pr/pboling/sanitize_email
|
|
154
|
+
[🧮prs-c]: https://github.com/pboling/sanitize_email/pulls?q=is%3Apr+is%3Aclosed
|
|
155
|
+
[🧮prs-c-img]: https://img.shields.io/github/issues-pr-closed/pboling/sanitize_email
|
|
156
|
+
|
|
157
|
+
<!-- 3️⃣ maintenance & linting -->
|
|
158
|
+
[🖇triage-help]: https://www.codetriage.com/pboling/sanitize_email
|
|
159
|
+
[🖇triage-help-img]: https://www.codetriage.com/pboling/sanitize_email/badges/users.svg
|
|
160
|
+
[🚎contributors]: https://gitlab.com/pboling/sanitize_email/-/graphs/main
|
|
161
|
+
[🚎contributors-img]: https://img.shields.io/github/contributors-anon/pboling/sanitize_email
|
|
162
|
+
[🖐style-wf]: https://github.com/pboling/sanitize_email/actions/workflows/style.yml
|
|
163
|
+
[🖐style-wf-img]: https://github.com/pboling/sanitize_email/actions/workflows/style.yml/badge.svg
|
|
164
|
+
<!-- TODO: tokei/lines shields badge is broken -->
|
|
165
|
+
[🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
|
|
166
|
+
[🧮kloc-img]: https://img.shields.io/tokei/lines/github.com/pboling/sanitize_email
|
|
167
|
+
|
|
168
|
+
<!-- 4️⃣ testing -->
|
|
169
|
+
[🏘sup-wf]: https://github.com/pboling/sanitize_email/actions/workflows/supported.yml
|
|
170
|
+
[🏘sup-wf-img]: https://github.com/pboling/sanitize_email/actions/workflows/supported.yml/badge.svg
|
|
171
|
+
[🚎heads-wf]: https://github.com/pboling/sanitize_email/actions/workflows/heads.yml
|
|
172
|
+
[🚎heads-wf-img]: https://github.com/pboling/sanitize_email/actions/workflows/heads.yml/badge.svg
|
|
173
|
+
[🖐uns-wf]: https://github.com/pboling/sanitize_email/actions/workflows/unsupported.yml
|
|
174
|
+
[🖐uns-wf-img]: https://github.com/pboling/sanitize_email/actions/workflows/unsupported.yml/badge.svg
|
|
175
|
+
[🧮mac-wf]: https://github.com/pboling/sanitize_email/actions/workflows/macos.yml
|
|
176
|
+
[🧮mac-wf-img]: https://github.com/pboling/sanitize_email/actions/workflows/macos.yml/badge.svg
|
|
177
|
+
[📗win-wf]: https://github.com/pboling/sanitize_email/actions/workflows/windows.yml
|
|
178
|
+
[📗win-wf-img]: https://github.com/pboling/sanitize_email/actions/workflows/windows.yml/badge.svg
|
|
179
|
+
|
|
180
|
+
<!-- 5️⃣ coverage & security -->
|
|
181
|
+
[🖇codecov-img♻️]: https://codecov.io/gh/pboling/sanitize_email/graph/badge.svg?token=Joire8DbSW
|
|
182
|
+
[🖇codecov]: https://codecov.io/gh/pboling/sanitize_email
|
|
183
|
+
[🏘coveralls]: https://coveralls.io/github/pboling/sanitize_email?branch=main
|
|
184
|
+
[🏘coveralls-img]: https://coveralls.io/repos/github/pboling/sanitize_email/badge.svg?branch=main
|
|
185
|
+
[🚎sec-pol]: https://gitlab.com/pboling/sanitize_email/-/blob/main/SECURITY.md
|
|
186
|
+
[🚎sec-pol-img]: https://img.shields.io/badge/security-policy-brightgreen.svg?style=flat
|
|
187
|
+
[🖐codeQL]: https://github.com/pboling/sanitize_email/security/code-scanning
|
|
188
|
+
[🖐codeQL-img]: https://github.com/pboling/sanitize_email/actions/workflows/codeql-analysis.yml/badge.svg
|
|
189
|
+
[🧮cov-wf]: https://github.com/pboling/sanitize_email/actions/workflows/coverage.yml
|
|
190
|
+
[🧮cov-wf-img]: https://github.com/pboling/sanitize_email/actions/workflows/coverage.yml/badge.svg
|
|
191
|
+
|
|
192
|
+
<!-- 6️⃣ resources -->
|
|
193
|
+
[🖇codementor]: https://www.codementor.io/peterboling?utm_source=github&utm_medium=button&utm_term=peterboling&utm_campaign=github
|
|
194
|
+
[🖇codementor-img]: https://cdn.codementor.io/badges/get_help_github.svg
|
|
195
|
+
[🏘chat]: https://gitter.im/pboling/sanitize_email
|
|
196
|
+
[🏘chat-img]: https://img.shields.io/gitter/room/pboling/sanitize_email.svg
|
|
197
|
+
[🚎blog]: http://www.railsbling.com/tags/sanitize_email/
|
|
198
|
+
[🚎blog-img]: https://img.shields.io/badge/blog-railsbling-brightgreen.svg?style=flat
|
|
199
|
+
[🖐wiki]: https://gitlab.com/pboling/sanitize_email/-/wikis/home
|
|
200
|
+
[🖐wiki-img]: https://img.shields.io/badge/wiki-examples-brightgreen.svg?style=flat
|
|
201
|
+
|
|
202
|
+
<!-- 7️⃣ spread 💖 -->
|
|
203
|
+
[🐦tweet-img]: https://img.shields.io/twitter/follow/galtzo.svg?style=social&label=Follow%20%40galtzo
|
|
204
|
+
[🐦tweet]: http://twitter.com/galtzo
|
|
205
|
+
[🚎blog]: http://www.railsbling.com/tags/debug_logging/
|
|
206
|
+
[🚎blog-img]: https://img.shields.io/badge/blog-railsbling-brightgreen.svg?style=flat
|
|
207
|
+
[🖇linkedin]: http://www.linkedin.com/in/peterboling
|
|
208
|
+
[🖇linkedin-img]: https://img.shields.io/badge/PeterBoling-blue?style=plastic&logo=linkedin
|
|
209
|
+
[✌️wellfound]: https://angel.co/u/peter-boling
|
|
210
|
+
[✌️wellfound-img]: https://img.shields.io/badge/peter--boling-orange?style=plastic&logo=angellist
|
|
211
|
+
[💲crunchbase]: https://www.crunchbase.com/person/peter-boling
|
|
212
|
+
[💲crunchbase-img]: https://img.shields.io/badge/peter--boling-purple?style=plastic&logo=crunchbase
|
|
213
|
+
[🐘ruby-mast]: https://ruby.social/@galtzo
|
|
214
|
+
[🐘ruby-mast-img]: https://img.shields.io/mastodon/follow/109447111526622197?domain=https%3A%2F%2Fruby.social&style=plastic&logo=mastodon&label=Ruby%20%40galtzo
|
|
215
|
+
[🐘floss-mast]: https://floss.social/@galtzo
|
|
216
|
+
[🐘floss-mast-img]: https://img.shields.io/mastodon/follow/110304921404405715?domain=https%3A%2F%2Ffloss.social&style=plastic&logo=mastodon&label=FLOSS%20%40galtzo
|
|
217
|
+
[🐘mast]: https://mastodon.social/@galtzo
|
|
218
|
+
[🐘mast-img]: https://img.shields.io/mastodon/follow/000924127?domain=https%3A%2F%2Fmastodon.social&style=plastic&logo=mastodon&label=Mastodon%20%40galtzo
|
|
219
|
+
[🌳linktree]: https://linktr.ee/galtzo
|
|
220
|
+
[🌳linktree-img]: https://img.shields.io/badge/galtzo-purple?style=plastic&logo=linktree
|
|
221
|
+
|
|
222
|
+
<!-- Maintainer Contact Links -->
|
|
223
|
+
[aboutme]: https://about.me/peter.boling
|
|
224
|
+
[coderme]: https://coderwall.com/Peter%20Boling
|
|
21
225
|
|
|
22
226
|
## Summary
|
|
23
227
|
|
|
@@ -51,11 +255,15 @@ Another very important use case for me is to transparently re-route email genera
|
|
|
51
255
|
|
|
52
256
|
If you install this gem on a production server (which I don't always do), you can load up script/console and override the to/cc/bcc on all emails for the duration of your console session. This allows you to poke and prod a live production instance, and route all email to your own inbox for inspection. The best part is that this can all be accomplished without changing a single line of your application code.
|
|
53
257
|
|
|
258
|
+
## Monitoring all email sent by server to a backup account
|
|
259
|
+
|
|
260
|
+
You may want to add a BCC automatically (e.g. to account-history@my-company.com) to every email sent by your system, for customer service purposes, and this gem allows that. Note that this may not be a good idea for all systems, for many reasons, e.g security!
|
|
261
|
+
|
|
54
262
|
## Using with a test suite as an alternative to the heavy email_spec
|
|
55
263
|
|
|
56
264
|
[email_spec](https://github.com/bmabey/email-spec) is a great gem, with awesome rspec matchers and helpers, but it has an undeclared dependency on ActionMailer. Sad face.
|
|
57
265
|
|
|
58
|
-
SanitizeEmail comes with some lightweight RspecMatchers covering most of what email_spec can do. It will help you test email functionality. It is useful when you are creating a gem to handle email features, or are writing a simple Ruby script, and don't want to pull in le Rails. SanitizeEmail has
|
|
266
|
+
SanitizeEmail comes with some lightweight RspecMatchers covering most of what email_spec can do. It will help you test email functionality. It is useful when you are creating a gem to handle email features, or are writing a simple Ruby script, and don't want to pull in le Rails. SanitizeEmail has two dependencies, `mail` gem, and `version_gem`. Your Mail system just needs to conform to `mail` gem's `register_interceptor` API.
|
|
59
267
|
|
|
60
268
|
## Install Like a Boss
|
|
61
269
|
|
|
@@ -103,6 +311,21 @@ There are three ways SanitizeEmail can be turned on; in order of precedence they
|
|
|
103
311
|
SanitizeEmail::Config.configure {|config| config[:activation_proc] = Proc.new { true } } # by default :activation_proc is false
|
|
104
312
|
```
|
|
105
313
|
|
|
314
|
+
### Examples
|
|
315
|
+
|
|
316
|
+
#### Only allow email to a specific domain
|
|
317
|
+
|
|
318
|
+
This works by ensuring that all recipients have the "allowed" domain.
|
|
319
|
+
In other words, none of the recipients have a domain other than the allowed domain.
|
|
320
|
+
|
|
321
|
+
```ruby
|
|
322
|
+
ALLOWED_DOMAIN = 'example.com'
|
|
323
|
+
# NOTE: you may need to check CC and BCC also, depending on your use case...
|
|
324
|
+
config[:activation_proc] = ->(message) do
|
|
325
|
+
!Array(message.to).any? { |recipient| Mail::Address.new(recipient).domain != ALLOWED_DOMAIN }
|
|
326
|
+
end
|
|
327
|
+
```
|
|
328
|
+
|
|
106
329
|
### Notes
|
|
107
330
|
|
|
108
331
|
Number 1, above, is the method used by the SanitizeEmail.sanitary block.
|
|
@@ -140,6 +363,8 @@ end
|
|
|
140
363
|
|
|
141
364
|
Keep in mind, this is ruby (and possibly rails), so you can add conditionals or utilize different environment.rb files to customize these settings on a per-environment basis.
|
|
142
365
|
|
|
366
|
+
## Override the override
|
|
367
|
+
|
|
143
368
|
But wait there's more:
|
|
144
369
|
|
|
145
370
|
Let's say you have a method in your model that you can call to test the signup email. You want to be able to test sending it to any user at any time... but you don't want the user to ACTUALLY get the email, even in production. A dilemma, yes? Not anymore!
|
|
@@ -150,7 +375,9 @@ To override the environment based switch use `force_sanitize`, which is normally
|
|
|
150
375
|
SanitizeEmail.force_sanitize = true
|
|
151
376
|
```
|
|
152
377
|
|
|
153
|
-
|
|
378
|
+
When testing your email in a console, you can manipulate how email will be handled in this way.
|
|
379
|
+
|
|
380
|
+
There are also two methods that take a block and turn SanitizeEmail on or off (see section on Thread Safety below):
|
|
154
381
|
|
|
155
382
|
Regardless of the Config settings of SanitizeEmail you can do a local override to force unsanitary email in any environment.
|
|
156
383
|
|
|
@@ -180,6 +407,36 @@ You have access to all the same configuration options in the parameter hash as y
|
|
|
180
407
|
end
|
|
181
408
|
```
|
|
182
409
|
|
|
410
|
+
## Configuration Options
|
|
411
|
+
|
|
412
|
+
As used in the "Description" column below, `engaged` means: `SanitizeEmail.activate?(message) # => true`.
|
|
413
|
+
This happens in a few different ways, and two of them are in the config below (`engage` and `activation_proc`).
|
|
414
|
+
|
|
415
|
+
| Option | Type (Yard format) | Description |
|
|
416
|
+
|---------------------------------------------|--------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|
|
|
417
|
+
| sanitized_to | [String, Array[String]] | (when engaged) Override CC field with these addresses |
|
|
418
|
+
| sanitized_cc | [String, Array[String]] | (when engaged) Override CC field with these addresses |
|
|
419
|
+
| sanitized_bcc | [String, Array[String]] | (when engaged) Override BCC field with these addresses |
|
|
420
|
+
| good_list | [Array[String]] | (when engaged) Email addresses to allow to pass-through without overriding |
|
|
421
|
+
| bad_list | [Array[String]] | (when engaged) Email addresses to be removed from message's TO, CC, & BCC |
|
|
422
|
+
| environment | [String, #to_s, Proc, Lambda, #call] | (when engaged) The environment value to use wherever it is added to message (e.g. in the subject line) |
|
|
423
|
+
| use_actual_email_as_sanitized_user_name | [Boolean] | (when engaged) Use "real" email address as username for sanitized email address (e.g. "real at example.com <sanitized@example.com>") |
|
|
424
|
+
| use_actual_email_prepended_to_subject | [Boolean] | (when engaged) Use "real" email address prepended to subject (e.g. "real at example.com Original Subject") |
|
|
425
|
+
| use_actual_environment_prepended_to_subject | [Boolean] | (when engaged) Use `environment` prepended to subject (e.g. "{{ STAGING }} Original Subject") |
|
|
426
|
+
| engage | [Boolean, nil] | Boolean will turn engage or disengage this gem, while `nil` ignores this setting and instead checks `activation_proc` |
|
|
427
|
+
| activation_proc | [Proc, Lambda, #call] | When checked, due to `engage: nil`, the result will either engage or disengage this gem |
|
|
428
|
+
|
|
429
|
+
## Thread Safety
|
|
430
|
+
|
|
431
|
+
So long as you don't change the config after initializing it at runtime, you'll be fine.
|
|
432
|
+
Like many Ruby tools' config objects, it is a single config object, shared by all threads.
|
|
433
|
+
The helpers like `sanitary`, `unsanitary`, `janitor`, and `force_sanitize`
|
|
434
|
+
are intended to be used in single threaded environments,
|
|
435
|
+
like a test suite, or a console session.
|
|
436
|
+
|
|
437
|
+
I doubt I'll ever have a need for runtime reconfiguration of the config,
|
|
438
|
+
so I doubt I'll ever have a reason to make it "more" thread safe than it is now, but PRs are welcome!
|
|
439
|
+
|
|
183
440
|
## Use sanitize_email in your test suite!
|
|
184
441
|
|
|
185
442
|
### rspec
|
|
@@ -222,10 +479,10 @@ end
|
|
|
222
479
|
|
|
223
480
|
#### have_* matchers
|
|
224
481
|
|
|
225
|
-
These will look for an email address in any of the following
|
|
482
|
+
These will look for an email address in any of the following mail attributes:
|
|
226
483
|
|
|
227
484
|
```ruby
|
|
228
|
-
:from, :to, :cc, :bcc, :subject, :reply_to
|
|
485
|
+
[:from, :to, :cc, :bcc, :subject, :reply_to]
|
|
229
486
|
```
|
|
230
487
|
|
|
231
488
|
Example:
|
|
@@ -258,7 +515,7 @@ end
|
|
|
258
515
|
|
|
259
516
|
The `username` in the `:to` field is when the `:to` field is formatted like this:
|
|
260
517
|
|
|
261
|
-
`Peter Boling <sanitize_email@example.org>`
|
|
518
|
+
`"Peter Boling" <sanitize_email@example.org>`
|
|
262
519
|
|
|
263
520
|
Example:
|
|
264
521
|
|
|
@@ -269,6 +526,58 @@ context "the to field must have the username 'Peter Boling'" do
|
|
|
269
526
|
end
|
|
270
527
|
```
|
|
271
528
|
|
|
529
|
+
#### have_sanitized_to_header matcher
|
|
530
|
+
|
|
531
|
+
Matches any part of the value of the first sanitized to header (`"X-Sanitize-Email-To"`),
|
|
532
|
+
which could be formatted like this:
|
|
533
|
+
|
|
534
|
+
`"Peter Boling" <sanitize_email@example.org>`
|
|
535
|
+
|
|
536
|
+
NOTE: It won't match subsequent headers like `"X-Sanitize-Email-To-2"`, or `"X-Sanitize-Email-To-3"`.
|
|
537
|
+
|
|
538
|
+
Example:
|
|
539
|
+
|
|
540
|
+
```ruby
|
|
541
|
+
context "the first 'X-Sanitize-Email-To' header must have the username 'Peter Boling'" do
|
|
542
|
+
subject { Mail.deliver(@message_hash) }
|
|
543
|
+
it { should have_sanitized_to_header "Peter Boling" }
|
|
544
|
+
end
|
|
545
|
+
```
|
|
546
|
+
|
|
547
|
+
#### have_cc_username matcher
|
|
548
|
+
|
|
549
|
+
The `username` in the `:cc` field is when the `:c` field is formatted like this:
|
|
550
|
+
|
|
551
|
+
`"Peter Boling" <sanitize_email@example.org>`
|
|
552
|
+
|
|
553
|
+
Example:
|
|
554
|
+
|
|
555
|
+
```ruby
|
|
556
|
+
context "the cc field must have the username 'Peter Boling'" do
|
|
557
|
+
subject { Mail.deliver(@message_hash) }
|
|
558
|
+
it { should have_cc_username "Peter Boling" }
|
|
559
|
+
end
|
|
560
|
+
```
|
|
561
|
+
|
|
562
|
+
#### have_sanitized_cc_header matcher
|
|
563
|
+
|
|
564
|
+
Matches any part of the value of the first sanitized cc header (`"X-Sanitize-Email-Cc"`),
|
|
565
|
+
which could be formatted like this:
|
|
566
|
+
|
|
567
|
+
`"Peter Boling" <sanitize_email@example.org>`
|
|
568
|
+
|
|
569
|
+
NOTE: It won't match subsequent headers like `"X-Sanitize-Email-Cc-2"`, or `"X-Sanitize-Email-Cc-3"`.
|
|
570
|
+
|
|
571
|
+
Example:
|
|
572
|
+
|
|
573
|
+
```ruby
|
|
574
|
+
context "the first 'X-Sanitize-Email-Cc' header must have the username 'Peter Boling'" do
|
|
575
|
+
subject { Mail.deliver(@message_hash) }
|
|
576
|
+
it { should have_sanitized_cc_header "Peter Boling" }
|
|
577
|
+
end
|
|
578
|
+
```
|
|
579
|
+
|
|
580
|
+
|
|
272
581
|
### non-rspec (Test::Unit, mini-test, etc)
|
|
273
582
|
|
|
274
583
|
In your setup file:
|
|
@@ -316,28 +625,51 @@ Peter Boling is the original author of the code, and current maintainer.
|
|
|
316
625
|
|
|
317
626
|
Thanks to John Trupiano for turning Peter's original Rails plugin into this gem!
|
|
318
627
|
|
|
319
|
-
##
|
|
628
|
+
## 🤝 Contributing
|
|
629
|
+
|
|
630
|
+
See [CONTRIBUTING.md][🤝contributing]
|
|
320
631
|
|
|
321
|
-
|
|
632
|
+
[🤝contributing]: CONTRIBUTING.md
|
|
322
633
|
|
|
323
|
-
|
|
634
|
+
### You can help!
|
|
324
635
|
|
|
325
|
-
Take a look at the `reek` list which is the file called `REEK` and
|
|
636
|
+
Take a look at the `reek` list which is the file called `REEK` and start fixing things.
|
|
326
637
|
|
|
327
638
|
To refresh the `reek` list:
|
|
328
639
|
|
|
329
640
|
`bundle exec reek > REEK`
|
|
330
641
|
|
|
331
|
-
|
|
642
|
+
Then follow these instructions:
|
|
332
643
|
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
1. Fork it
|
|
644
|
+
1. Fork the repository
|
|
336
645
|
2. Create your feature branch (`git checkout -b my-new-feature`)
|
|
337
|
-
3.
|
|
338
|
-
4.
|
|
339
|
-
5.
|
|
340
|
-
6.
|
|
646
|
+
3. Make some fixes.
|
|
647
|
+
4. Commit your changes (`git commit -am 'Added some feature'`)
|
|
648
|
+
5. Push to the branch (`git push origin my-new-feature`)
|
|
649
|
+
6. Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
|
|
650
|
+
7. Create new Pull Request.
|
|
651
|
+
|
|
652
|
+
## 🌈 Contributors
|
|
653
|
+
|
|
654
|
+
[![Contributors][🌈contrib-rocks-img]][🐙hub-contrib]
|
|
655
|
+
|
|
656
|
+
Contributor tiles (GitHub only) made with [contributors-img][🌈contrib-rocks].
|
|
657
|
+
|
|
658
|
+
Learn more about, or become one of, our 🎖 contributors on:
|
|
659
|
+
|
|
660
|
+
| Any | Of | These | DVCS |
|
|
661
|
+
|-------------------------------------|---------------------------------------|-------------------------------------|-------------------------------------|
|
|
662
|
+
| [🐙hub contributors][🐙hub-contrib] | [🧊berg contributors][🧊berg-contrib] | [🛖hut contributors][🛖hut-contrib] | [🧪lab contributors][🧪lab-contrib] |
|
|
663
|
+
|
|
664
|
+
[comment]: <> ( DVCS CONTRIB LINKS )
|
|
665
|
+
|
|
666
|
+
[🌈contrib-rocks]: https://contrib.rocks
|
|
667
|
+
[🌈contrib-rocks-img]: https://contrib.rocks/image?repo=pboling/sanitize_email
|
|
668
|
+
|
|
669
|
+
[🧊berg-contrib]: https://codeberg.org/pboling/sanitize_email/activity
|
|
670
|
+
[🐙hub-contrib]: https://github.com/pboling/sanitize_email/graphs/contributors
|
|
671
|
+
[🛖hut-contrib]: https://git.sr.ht/~galtzo/pboling-sanitize_email/log/
|
|
672
|
+
[🧪lab-contrib]: https://gitlab.com/pboling/sanitize_email/-/graphs/main?ref_type=heads
|
|
341
673
|
|
|
342
674
|
## Running Specs
|
|
343
675
|
|
|
@@ -347,35 +679,52 @@ appraisal install
|
|
|
347
679
|
appraisal rake test
|
|
348
680
|
```
|
|
349
681
|
|
|
350
|
-
Run the whole travis compatibility matrix:
|
|
351
|
-
```
|
|
352
|
-
rake wwtd:bundle
|
|
353
|
-
rake wwtd
|
|
354
|
-
```
|
|
355
|
-
|
|
356
682
|
Sometimes also:
|
|
357
683
|
```
|
|
358
684
|
appraisal update
|
|
359
685
|
```
|
|
360
686
|
|
|
361
|
-
|
|
687
|
+
### Code Coverage
|
|
688
|
+
|
|
689
|
+
[![Coverage Graph][🔑codecov-g]][🖇codecov]
|
|
690
|
+
|
|
691
|
+
[🔑codecov-g]: https://codecov.io/gh/pboling/sanitize_email/graphs/tree.svg?token=Joire8DbSW
|
|
692
|
+
|
|
693
|
+
## 🪇 Code of Conduct
|
|
694
|
+
|
|
695
|
+
Everyone interacting in this project's codebases, issue trackers,
|
|
696
|
+
chat rooms and mailing lists is expected to follow the [code of conduct][🪇conduct].
|
|
362
697
|
|
|
363
|
-
|
|
364
|
-
Violations of this scheme should be reported as bugs. Specifically,
|
|
365
|
-
if a minor or patch version is released that breaks backward
|
|
366
|
-
compatibility, a new version should be immediately released that
|
|
367
|
-
restores compatibility. Breaking changes to the public API will
|
|
368
|
-
only be introduced with new major versions.
|
|
698
|
+
[🪇conduct]: CODE_OF_CONDUCT.md
|
|
369
699
|
|
|
370
|
-
|
|
371
|
-
|
|
700
|
+
## 📌 Versioning
|
|
701
|
+
|
|
702
|
+
This Library adheres to [Semantic Versioning 2.0.0][📌semver].
|
|
703
|
+
Violations of this scheme should be reported as bugs.
|
|
704
|
+
Specifically, if a minor or patch version is released that breaks backward compatibility,
|
|
705
|
+
a new version should be immediately released that restores compatibility.
|
|
706
|
+
Breaking changes to the public API will only be introduced with new major versions.
|
|
707
|
+
|
|
708
|
+
To get a better understanding of how SemVer is intended to work over a project's lifetime,
|
|
709
|
+
read this article from the creator of SemVer:
|
|
710
|
+
|
|
711
|
+
- ["Major Version Numbers are Not Sacred"][📌major-versions-not-sacred]
|
|
712
|
+
|
|
713
|
+
As a result of this policy, you can (and should) specify a dependency on these libraries using
|
|
714
|
+
the [Pessimistic Version Constraint][📌pvc] with two digits of precision.
|
|
372
715
|
|
|
373
716
|
For example:
|
|
374
717
|
|
|
375
718
|
```ruby
|
|
376
|
-
spec.add_dependency
|
|
719
|
+
spec.add_dependency "sanitize_email", "~> 2.0"
|
|
377
720
|
```
|
|
378
721
|
|
|
722
|
+
[comment]: <> ( 📌 VERSIONING LINKS )
|
|
723
|
+
|
|
724
|
+
[📌pvc]: http://guides.rubygems.org/patterns/#pessimistic-version-constraint
|
|
725
|
+
[📌semver]: http://semver.org/
|
|
726
|
+
[📌major-versions-not-sacred]: https://tom.preston-werner.com/2022/05/23/major-version-numbers-are-not-sacred.html
|
|
727
|
+
|
|
379
728
|
## References
|
|
380
729
|
|
|
381
730
|
* [Source Code](http://github.com/pboling/sanitize_email)
|
|
@@ -383,16 +732,23 @@ spec.add_dependency 'sanitize_email', '~> 1.3'
|
|
|
383
732
|
* [Peter's Original Writeup](http://galtzo.blogspot.com/2008/11/sanitize-email-never-worry-about.html)
|
|
384
733
|
* [Using sanitize_email to Preview HTML Emails Locally](http://blog.smartlogicsolutions.com/2009/04/30/using-sanitize-email-to-preview-html-emails-locally/)
|
|
385
734
|
|
|
386
|
-
##
|
|
735
|
+
## 📄 License
|
|
736
|
+
|
|
737
|
+
The gem is available as open source under the terms of
|
|
738
|
+
the [MIT License][📄license] [![License: MIT][📄license-img]][📄license-ref].
|
|
739
|
+
See [LICENSE.txt][📄license] for the official [Copyright Notice][📄copyright-notice-explainer].
|
|
740
|
+
|
|
741
|
+
[comment]: <> ( 📄 LEGAL LINKS )
|
|
742
|
+
|
|
743
|
+
[📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year
|
|
744
|
+
[📄license]: LICENSE.txt
|
|
745
|
+
[📄license-ref]: https://opensource.org/licenses/MIT
|
|
746
|
+
[📄license-img]: https://img.shields.io/badge/License-MIT-green.svg
|
|
747
|
+
|
|
748
|
+
### © Copyright
|
|
387
749
|
|
|
388
|
-
* MIT License - See [LICENSE file][license] in this project
|
|
389
750
|
* Copyright (c) 2009 [John Trupiano](http://smartlogicsolutions.com/wiki/John_Trupiano) of [SmartLogic Solutions, LLC](http://www.smartlogicsolutions.com)
|
|
390
|
-
* Copyright (c) 2008-
|
|
751
|
+
* Copyright (c) 2008 - 2018, 2020, 2022, 2024 [Peter H. Boling][peterboling] of [Rails Bling][railsbling]
|
|
391
752
|
|
|
392
|
-
[license]: LICENSE
|
|
393
|
-
[semver]: http://semver.org/
|
|
394
|
-
[pvc]: http://guides.rubygems.org/patterns/#pessimistic-version-constraint
|
|
395
753
|
[railsbling]: http://www.railsbling.com
|
|
396
754
|
[peterboling]: http://www.peterboling.com
|
|
397
|
-
[documentation]: http://rdoc.info/github/pboling/sanitize_email/frames
|
|
398
|
-
[homepage]: http://www.railsbling.com/tags/sanitize_email/
|
data/SECURITY.md
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# Security Policy
|
|
2
|
+
|
|
3
|
+
## Supported Versions
|
|
4
|
+
|
|
5
|
+
| Version | Supported |
|
|
6
|
+
|---------|-----------|
|
|
7
|
+
| 2.x | ✅ |
|
|
8
|
+
| 1.x | ❌ |
|
|
9
|
+
| 0.x | ❌ |
|
|
10
|
+
|
|
11
|
+
## Reporting a Vulnerability
|
|
12
|
+
|
|
13
|
+
Peter Boling is the primary maintainer of this gem. Please find a way
|
|
14
|
+
to [contact him directly](https://railsbling.com/contact) to report the issue. Include as much relevant information as
|
|
15
|
+
possible.
|