mailscope 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: db87fb72ccde481718a35a6a8902eeb1e2fbfc423c8292e17b0d5fb3b97afa0e
+  data.tar.gz: 85b4a41a9c9afb1231092a1030e631ca22fef3b9113a24b8b734281343dd6de7
+SHA512:
+  metadata.gz: df401455be0fd9677dbd74b2c2aed038277370f61b8f15ec8f0e841bb31c39365fafdaa20ea691d1faa9660d0eb93fb0b29c53f010037e2f59b8fabe29916430
+  data.tar.gz: ea923fff2de475991245b5850b26ef21a9619588f3b4b922e9989d95d75d546c7319ba220d0c7fb861736f79a0231ca5833a29b8953cfdb2a9c3e6d2b39f1e6b

data/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+## [Unreleased]
+
+[Unreleased]: https://github.com/renatomeloferraz/mailscope/compare/v0.1.0...HEAD
+
+## [0.1.0] — 2026-08-22
+
+[0.1.0]: https://github.com/renatomeloferraz/mailscope/releases/tag/v0.1.0
+
+First release. A fork of `letter_opener_web` 3.0.0, rebuilt.
+
+### New foundation
+
+- Own delivery method, storing the original `.eml` plus a `metadata.json` per
+  message. Headers come from the `mail` gem instead of a regex over rendered
+  HTML — no more `UNABLE TO PARSE HEADERS`, and no more `letter_opener`
+  dependency.
+- Storage adapters (`Mailscope::Storage::Base`), with `:filesystem` built in.
+- Lexicographically sortable, time-ordered ids: listing no longer stats every
+  directory nor reads every message in full.
+- Retention policy (`max_letters`, `max_age`) applied after each delivery.
+
+### Requirements
+
+- Ruby >= 3.1, Rails >= 7.1. CI runs the suite against Rails 7.1, 7.2, 8.0 and
+  8.1 on the Ruby versions each of them supports.
+
+### Interface
+
+- Three-column layout: mailboxes per recipient, message list, reading pane.
+- Search across subject, sender, recipient, mailer and plain-text body. The
+  `mailbox` and `only` query parameters narrow the list further, including on
+  the JSON endpoint.
+- HTML, Text, Source (raw `.eml`), Headers and Attachments tabs.
+- Responsive preview (desktop / tablet 768px / mobile 390px).
+- Opt-in live updates: the list refreshes itself when new mail arrives, and
+  the switch state is remembered per browser.
+- Real light/dark theme with a persisted one-click toggle, starting from the
+  OS preference. The HTML preview stays on white on purpose; the plain-text
+  view follows the theme.
+- Inter as the interface typeface, bundled with the gem.
+- Keyboard navigation and a shortcuts dialog.
+- `.eml` and attachment downloads.
+- The document title carries the captured message count and tracks the list.
+- Internationalisation: English and Brazilian Portuguese.
+
+### Security
+
+- First-class `config.authenticate_with`.
+- The preview runs in a sandboxed iframe under a strict CSP; scripts never run
+  and remote content is blocked by default, with a visible count.
+- Inline (`cid:`) images become `data:` URIs, so the frame needs no
+  `allow-same-origin`.
+
+### Front end
+
+- jQuery, jquery-ujs, Bootstrap and Bootstrap Icons removed: roughly 277 KB
+  inlined into every HTML response and re-run through ERB on each request.
+  Replaced by own CSS and JS served as immutably cached assets.
+- No `data-remote` / `data-method`: destructive actions use `fetch` with
+  `DELETE` and a CSRF token, which also removes the Turbo conflict.
+
+### Compatibility
+
+- `:letter_opener_web` is still registered as a delivery method.
+- `config.letters_location` aliases `config.location`.
+- Old `letter_opener` directories are listed read-only.

data/LICENSE.txt

@@ -0,0 +1,27 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Renato Ferraz
+Copyright (c) 2013-2026 Fabio Rehm, David Muto and letter_opener_web contributors
+
+Mailscope started as a fork of letter_opener_web
+(https://github.com/fgrehm/letter_opener_web), which is itself inspired by
+letter_opener (https://github.com/ryanb/letter_opener). Both are MIT licensed
+and their copyright notices are preserved above.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,210 @@
+# Mailscope
+
+A mail inspector for Rails development and staging environments. It captures
+everything your app sends and gives you a fast web UI to **search, preview and
+inspect** it: HTML, plain text, the raw `.eml`, real headers and attachments —
+with one mailbox per recipient, responsive previews and remote-content
+blocking.
+
+Mailscope started as a fork of
+[letter_opener_web](https://github.com/fgrehm/letter_opener_web) and was
+rebuilt on a different foundation: instead of regex-matching the HTML that
+`letter_opener` already rendered, it stores the original `.eml` plus a small
+metadata index, and reads everything from there.
+
+## Installation
+
+Requires Ruby 3.1+ and Rails 7.1+.
+
+```ruby
+group :development do
+  gem 'mailscope'
+end
+```
+
+`config/routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+  mount Mailscope::Engine, at: '/mailscope' if Rails.env.development?
+end
+```
+
+`config/environments/development.rb`:
+
+```ruby
+config.action_mailer.delivery_method = :mailscope
+```
+
+That's it. Send an email and open `http://localhost:3000/mailscope`.
+
+## What it does
+
+| | |
+|---|---|
+| **Mailboxes per recipient** | One entry per address that received mail (To, Cc and Bcc), with counts. |
+| **Search** | Subject, sender, recipient, mailer class and the plain-text body. |
+| **HTML / Text / Source / Headers / Attachments tabs** | The raw `.eml` and the real headers, not an approximation. |
+| **Responsive preview** | Switch the preview width between desktop, tablet (768px) and mobile (390px). |
+| **Remote-content blocking** | The preview runs in a sandboxed iframe under a strict CSP; external images are blocked by default and the app tells you how many. Inline (`cid:`) images become `data:` URIs. |
+| **Live updates** | Opt-in: flip the switch in the header and the list refreshes itself when new mail arrives. The choice sticks per browser. |
+| **Light / dark theme** | A real theme with a one-click toggle — not a `filter: invert()` hack. The HTML preview deliberately stays on white: it is the message as its recipients will see it. The plain-text view, which has no sender design to preserve, follows the theme. |
+| **Keyboard** | `j`/`k` to move, `/` to search, `x` to delete, `1`–`5` to switch tabs, `?` for the full list. |
+| **`.eml` download** | Reopen a message in any client, or attach it to a bug report. |
+| **JSON API** | `GET /mailscope/?format=json` — handy in system tests. Accepts `q`, `mailbox` and `only=attachments\|html\|text`. |
+| **Retention** | Old messages are discarded automatically; `tmp/` does not grow forever. |
+| **i18n** | English and Brazilian Portuguese, following the app's `I18n.locale`. |
+
+## Configuration
+
+```ruby
+Mailscope.configure do |config|
+  # Where messages live. Default: Rails.root.join('tmp', 'mailscope')
+  config.location = Rails.root.join('tmp', 'mailscope')
+
+  # :filesystem (default) or any object implementing Mailscope::Storage::Base
+  config.storage = :filesystem
+
+  # Retention, applied after every delivery. nil disables the check.
+  config.max_letters = 500
+  config.max_age     = 7.days
+
+  # Access guard. Receives the ActionDispatch::Request; return falsy to deny.
+  config.authenticate_with = ->(request) { request.local? }
+
+  # Initial state of the "remote content" switch in the preview pane.
+  config.block_remote_content = true
+
+  # Browser polling for newly delivered mail. This is only the default state of
+  # the header switch — the user's own choice is remembered per browser.
+  config.auto_refresh          = false
+  config.auto_refresh_interval = 3 # seconds
+
+  # :system (default), :light or :dark — the user can override it in the UI.
+  config.default_theme = :system
+
+  config.title = 'Mailscope'
+end
+```
+
+### Authentication
+
+People routinely mount tools like this on staging. Rather than relying on you
+remembering to wrap the route in a constraint, `authenticate_with` is part of
+the configuration:
+
+```ruby
+Mailscope.configure do |config|
+  config.authenticate_with = lambda do |request|
+    ActiveSupport::SecurityUtils.secure_compare(
+      request.headers['X-Mailscope-Token'].to_s, ENV.fetch('MAILSCOPE_TOKEN')
+    )
+  end
+end
+```
+
+The block is evaluated in the controller's context, so `session`, `cookies` and
+your application's helpers are available.
+
+## Staging / pre-production use
+
+1. Move the gem out of the `:development` group in your `Gemfile`.
+2. Set `config.action_mailer.delivery_method = :mailscope` for that environment.
+3. Mount the route there and **configure `authenticate_with`**.
+
+The `:filesystem` adapter keeps messages on the process's own disk. With more
+than one instance (several dynos, a separate worker) each instance only sees
+what it delivered itself — write a shared storage adapter
+(`Mailscope::Storage::Base` has seven methods) and point `config.storage` at it.
+
+## Preview security
+
+The message body is served from its own route and rendered inside an iframe
+with `sandbox` (no `allow-scripts`, no `allow-same-origin`) under a strict
+response `Content-Security-Policy`:
+
+```
+default-src 'none'; script-src 'none'; frame-src 'none'; object-src 'none';
+form-action 'none'; base-uri 'none'; style-src 'unsafe-inline' data:;
+font-src data:; img-src data:
+```
+
+With the remote-content switch on, `img-src` additionally accepts `https:` and
+`http:`. Scripts never run.
+
+## Migrating from letter_opener_web
+
+```diff
+-gem 'letter_opener_web', '~> 3.0'
++gem 'mailscope'
+```
+
+```diff
+-mount LetterOpenerWeb::Engine, at: '/letter_opener'
++mount Mailscope::Engine, at: '/mailscope'
+```
+
+The `:letter_opener_web` delivery method stays registered as an alias, so
+`config.action_mailer.delivery_method` does not have to change right away.
+`config.letters_location` also still works as an alias of `config.location`,
+and old `letter_opener` directories (`1358825621_ba83a22/rich.html`) are listed
+read-only.
+
+Worth knowing:
+
+- New messages are stored as `.eml` + `metadata.json`, not as rendered HTML.
+  `letter_opener` is no longer a dependency.
+- Routes changed (`/messages/:id`, `DELETE` instead of `POST .../delete`).
+- No jQuery, jquery-ujs or Bootstrap inlined into the HTML any more.
+
+## Development
+
+```bash
+bin/setup
+bin/rspec
+bin/rubocop
+
+# against another Rails version
+BUNDLE_GEMFILE=gemfiles/rails_7_1.gemfile bundle install
+BUNDLE_GEMFILE=gemfiles/rails_7_1.gemfile bundle exec rspec
+```
+
+To run the bundled example app with sample messages:
+
+```bash
+bundle exec rackup spec/dummy/config.ru -p 3123
+```
+
+Then open `http://localhost:3123/seed` to generate messages and
+`http://localhost:3123/mailscope` for the UI. `MAILSCOPE_LOCALE=en` runs it in
+English, `pt-BR` in Portuguese.
+
+## Bundled assets
+
+The UI ships [Inter](https://rsms.me/inter/) (SIL OFL 1.1, see
+[INTER-LICENSE.txt](app/assets/mailscope/INTER-LICENSE.txt)) as two woff2
+subsets served from the engine's own digested asset path. Nothing is fetched
+from a CDN, so the UI looks the same offline and no request leaves the machine.
+
+## Releasing
+
+Publishing runs from a tag, authenticated with RubyGems trusted publishing
+(OIDC) — there is no API key in the repository secrets.
+
+1. Bump `Mailscope::VERSION` and move the `Unreleased` notes into a dated
+   section in [CHANGELOG.md](CHANGELOG.md).
+2. Commit, then `git tag vX.Y.Z && git push --tags`.
+
+The release workflow reruns the suite, checks the tag against the version,
+then builds and pushes the gem via `rake release`. Write the GitHub release
+notes by hand afterwards if you want them.
+
+## Credits
+
+Mailscope is a fork of [letter_opener_web](https://github.com/fgrehm/letter_opener_web)
+by Fabio Rehm and David Muto, which in turn grew out of
+[letter_opener](https://github.com/ryanb/letter_opener) by Ryan Bates. Both MIT.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/app/assets/mailscope/INTER-LICENSE.txt

@@ -0,0 +1,92 @@
+Copyright (c) 2016 The Inter Project Authors (https://github.com/rsms/inter)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION AND CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

data/app/assets/mailscope/favicon.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
+  <rect width="32" height="32" rx="8" fill="#5a5bd6"/>
+  <path d="M7 11.5A1.5 1.5 0 0 1 8.5 10h15a1.5 1.5 0 0 1 1.5 1.5v9a1.5 1.5 0 0 1-1.5 1.5h-15A1.5 1.5 0 0 1 7 20.5z"
+        fill="none" stroke="#fff" stroke-width="2"/>
+  <path d="m7.5 11.5 8.5 6 8.5-6" fill="none" stroke="#fff" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>