cloudflare-email 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5188438b941345c4164baca6ab1400e2fc74259c5fdd209a6d2ed9ac618147b5
-  data.tar.gz: 5e3a6ff25c460c0a73ffb3fdf44dcc62f87679f4278e328c605291d62de35fa9
+  metadata.gz: c65b29d22af39c25cb2affb776984bc9a9086bcad75c7388c2017692f61eb9ef
+  data.tar.gz: 2c0d1f15f4159e780257260af62cca8d414c7cc00d7c1c8b2677ac243cf81b04
 SHA512:
-  metadata.gz: 77fe9d9c571311065e9d10d00e2c021156113ff63dec5a970f63456a6cee9d3413bfe157dcfd8e37992e5b747e1ab957d342bfc01a399d41e2c3838462067aa3
-  data.tar.gz: bf580baaec84aa3dc8894f0fbc9b770ca4fe2521a1534b248fe75bd67812a40adaf4538d321a7740b911b1fc42b80e5fd468418c4d804d635f5496710591add6
+  metadata.gz: 4b76b7c08c99da504f7c90bbfb79f6f3130345e128c0fad9988a1449270d79019ffa5af8fb62a0759ad881c56019ffe6d9f6b967d13136e988b9e98ef6d7043e
+  data.tar.gz: d3f2d2573c6d41140ceff2395c4aa84194eb10ad2c56379df133f1fa1687424b009513800e4c67d1077584750146c2f5b9e0dfedfb53d2b9a351c5f207f80636

data/CHANGELOG.md

@@ -1,5 +1,114 @@
 # Changelog
 
+## 0.4.0 — 2026-09-14
+
+Released alongside Mailbox Kit 0.1.0. Cloudflare installs the core automatically.
+Existing installations should follow the [core upgrade guide](mailbox-kit/docs/upgrading.md).
+
+- Allow receiving domains without a sending account. The upgrade generator
+  preserves existing directory records while making account ownership optional.
+
+- Index inbox memberships by inbound email for recipient isolation checks,
+  retention and purge. New schemas include the index; `mailbox_kit:upgrade`
+  generates a data-preserving migration for existing installations.
+- Delegate shared configuration to Mailbox Kit and isolate Cloudflare session
+  additions in an integration module. Provide a short core quickstart plus
+  packaged integration and upgrade guides.
+
+- Lean on Action Mailbox for original email records, processing and configurable
+  retention. Add idempotent attachment of existing Rails records and source-based
+  receiving that resolves duplicates for inbox membership. Share the persistence
+  bridge with Cloudflare while preserving its signed delivery identity and legacy
+  duplicate return value. Reuse Rails' model load hook for selective retention.
+
+- Extract provider-neutral mailbox storage, recipient routing, optional tenancy,
+  raw-message retention, Rails job context and the server-rendered UI into the
+  sibling `mailbox-kit` gem. Cloudflare APIs, Worker transport, sending outbox and
+  delivery feedback remain in `cloudflare-email`. Preserve existing table names,
+  public constants, job payload keys and mounted Cloudflare engine routes.
+  See [Mailbox Kit](mailbox-kit/README.md) for standalone setup and release order.
+
+- Add a cited one-time domain setup guide for both receiving domains and dynamic
+  organization subdomains, shared between Worker templates. Add a read-only
+  `npm run check:subdomains` DNS helper with named/fresh probes and explicit limits
+  on what DNS can verify. The Worker transport and gem routing behavior are unchanged.
+
+## 0.3.0 — 2026-09-13
+
+See [upgrading from 0.2](docs/upgrading-0.3.md) before deploying the updated Worker.
+
+- Add a standalone Deploy to Cloudflare template with R2/Queue provisioning,
+  secret prompts, scheduled recovery, and logs. CI checks runtime/configuration
+  synchronization with the gem's Worker and tests an isolated template copy.
+
+- Make durable inbound delivery the Worker default, with explicit direct fallback: commit original mail and envelope context
+  to R2 before Worker acceptance, deliver queue pointers with fresh signatures,
+  and recover pending mail through a bounded scheduled sweep. Rails errors,
+  lost responses, enqueue failures and exhausted queue retries retain pending
+  mail. Provisioning, protected storage and monitoring remain explicit.
+- Make missing Message-ID fallback deterministic across Rails hosts so replay
+  after a deployment does not create another inbound record. Original MIME and
+  parseable provider Message-IDs remain unchanged.
+- Add optional authenticated Routing analytics delivery confirmation with
+  encrypted immutable receipts, strict single-envelope-recipient correlation,
+  replay and transactional callbacks. Sending acceptance remains unchanged;
+  missing or ambiguous evidence never authorizes a resend.
+- Bound shared sending/queue HTTP responses by streamed bytes and a total
+  per-attempt deadline; disable implicit HTTP retries and sanitize transport
+  failures. Sending and queue acknowledgement ambiguity stays safe to replay
+  through durable receipts rather than resending accepted email.
+- Document verified Routing destinations, separate analytics credentials and
+  explicit system-mail storage with optional SQLite tenancy.
+
+- Add optional domain catch-all receiving on an existing active mailbox address,
+  with explicit verification evidence and a unique active catch-all constraint.
+  Exact registered addresses always win, including rejected inactive addresses;
+  unknown local parts retain their actual envelope recipient without new aliases.
+  Destination snapshots identify fallback, while sending stays exact-address only.
+  A separate generator upgrades existing mailbox schemas; catch-all is never
+  enabled automatically.
+
+- Allow production Rails schema preloading to boot without a selected tenant.
+  Tenant model pool access still fails closed with
+  `Cloudflare::Email::ActiveRecord::TenantConnectionUnavailable`, an
+  `ActiveRecord::ConnectionNotEstablished` error retaining the original
+  `ConfigurationError` as its cause. No default tenant is selected.
+
+- Add a reusable Worker `relayEmail` pipeline with host backend/header policies,
+  bounded raw reads, optional fail-open archive hooks, safe HTTP outcomes and
+  deadlines. `archiveEmail` writes raw bytes and envelope metadata to an optional
+  R2 bucket. Default and custom forwarding share the same HTTP transport.
+- Keep provider authentication interpretation, archive keys, retry decisions and
+  fallback destinations with the host; existing default v2/v3 forwarding remains
+  compatible. Archive deadlines bound waiting but cannot cancel an in-flight write.
+
+- Add `Mailboxes.with_recipient` for active-address resolution and immutable
+  destination context with host-owned persistence, without ActionMailbox.
+- Yield the same destination from `Mailboxes.receive` so apps can link their
+  business records while retaining gem-managed raw email, metadata and membership
+  persistence. Host exceptions propagate instead of being reported as missing
+  mailbox records; existing no-argument receive blocks continue to work.
+
+- Add a bounded, Rails-independent `Ingress.verify` API for existing ingestion
+  pipelines, with optional ActionMailbox persistence and tenant registry routing.
+- Add opt-in v3 signatures for provider metadata supplied by custom Workers.
+  Metadata is authenticated transport evidence, not proof of sender authenticity.
+  Default Worker forwarding remains v2; upgrade Rails before enabling v3.
+- Verify signatures against exact timestamp header bytes; decimal parsing is
+  used only for freshness. The bundled Worker's timestamp format is unchanged.
+- Add GET-only `cloudflare:email:check_route` diagnostics for exact receiving-domain
+  DNS and Worker routing. Reports uncertainty without changing configuration or
+  claiming live delivery is verified.
+
+- Add an opt-in server-rendered mailbox management engine with host authentication,
+  mailbox/domain scoping and per-action permissions. Manage mailboxes and aliases,
+  suspend/resume, preview plain-text messages and mark read/archive without
+  JavaScript or asset pipeline dependencies. The engine is never mounted by default.
+
+- Fix managed domain and address activation in Rails apps with strict readonly
+  attributes enabled. Normalize immutable identities only when creating records;
+  later lifecycle updates retain the original domain and address.
+
 ## 0.2.0 — 2026-09-11
 
 - Add optional managed mailboxes: domain directory, addresses/aliases, lifecycle,

data/README.md

@@ -2,10 +2,21 @@
 
 Ruby client for [Cloudflare Email Service](https://developers.cloudflare.com/email-service/), with ActionMailer, authenticated ActionMailbox ingress, a forwarding Worker, and optional durable Rails sending and delivery-event tracking.
 
-Version **0.2.0**. Ruby 3.2+, Rails 7.2–8.1; Ruby 4.0 is tested with Rails 8.1. Supported test floors are Rails 7.2.3.2, 8.0.5.1, and 8.1.3.1. Prefer a maintained Ruby/Rails release for new applications. The plain Ruby client uses Ruby's standard libraries plus the Base64 gem. Node is optional: Worker deployment also works through the included Ruby deployer. See [security guidance](SECURITY.md) for deployment responsibilities.
+Version **0.4.0**, with **Mailbox Kit 0.1.0**. Ruby 3.2+, Rails 7.2–8.1; Ruby 4.0 is tested with Rails 8.1. Supported test floors are Rails 7.2.3.2, 8.0.5.1, and 8.1.3.1. Prefer a maintained Ruby/Rails release for new applications. Rails and database dependencies remain optional for the plain Ruby client. Node is optional: Worker deployment also works through the included Ruby deployer. See [security guidance](SECURITY.md) for deployment responsibilities.
+
+[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cole-robertson/cloudflare-email/tree/main/templates/deploy-to-cloudflare)
+
+Deploy the inbound Worker with guided R2/Queue provisioning and secret setup. [Prepare Rails and connect your email address](templates/deploy-to-cloudflare/README.md).
 
 ## Start here
 
+**Starting in 0.4.0:** provider-neutral mailbox functionality lives in
+the sibling [Mailbox Kit](mailbox-kit/README.md) gem. Existing Cloudflare setup
+continues to work; the core requires no Cloudflare account. Installing
+`cloudflare-email` also installs `mailbox-kit` 0.1.x.
+Existing mailbox installations should use the [core upgrade guide](mailbox-kit/docs/upgrading.md)
+to add the inbound lookup index without recreating their tables.
+
 **Sending email?** Start with the [step-by-step Rails guide](docs/getting-started.md).
 **Building a mailbox?** Follow the same guide through receiving, the SQLite-compatible outbox, and delivery tracking.
 **Using plain Ruby?** Jump to [Plain Ruby](#plain-ruby); Rails and a database are optional.
@@ -14,21 +25,30 @@ Version **0.2.0**. Ruby 3.2+, Rails 7.2–8.1; Ruby 4.0 is tested with Rails 8.1
 | --- | --- |
 | [Features at a glance](docs/features.md) | Everything the gem handles, and what your app supplies |
 | [Getting started](docs/getting-started.md) | Install, send your first email, receive replies, and save reliable send operations |
+| [Cloudflare domain setup](templates/worker/docs/domain-setup.md) | Configure once for many mailboxes or dynamic organization subdomains, with a Rebulk example and DNS checks |
+| [Hello-world Rails template](https://github.com/cole-robertson/cloudflare-email-rails-starter) | Clone a minimal SQLite mailbox app using the published gem and its management UI |
 | [Troubleshooting](docs/troubleshooting.md) | What to check when mail or delivery updates do not arrive |
 | [Managed mailboxes](docs/mailboxes.md) | Create inboxes and aliases, read/archive mail, and send from a mailbox |
+| [Management engine](docs/management-engine.md) | Mount an optional server-rendered mailbox UI using your app's authentication |
+| [Custom ingress](docs/custom-ingress.md) | Reuse authentication, signed metadata, and tenant routing in your existing ingestion pipeline |
+| [Routing diagnostics](docs/routing-diagnostics.md) | Inspect exact-domain DNS and Worker routes without changing infrastructure |
+| [Reusable Worker pipeline](templates/worker/README.md#reuse-the-transport-in-an-existing-worker) | Keep custom backend and archive policies while sharing bounded email forwarding |
+| [Durable inbound delivery](templates/worker/README.md#durable-inbound-delivery) | Store incoming mail in R2 and recover Rails outages with queued retries and scheduled recovery |
+| [Routing delivery confirmation](docs/routing-deliveries.md) | Confirm qualifying normal-address deliveries using authenticated Routing analytics |
 | [SQLite tenant databases](docs/activerecord-tenanted.md) | Give each organization its own SQLite database with `activerecord-tenanted` |
 | [Durable outbox](docs/outbox.md) | Detailed setup, callbacks, retries, and recovery |
 | [Delivery events](docs/delivery-events.md) | Cloudflare Queue setup and recipient status tracking |
-| [Upgrading to 0.2](docs/upgrading-0.2.md) | Changes needed for an existing installation |
+| [Upgrading to 0.4](mailbox-kit/docs/upgrading.md) | Core extraction and data-preserving migrations for existing mailboxes |
+| [Upgrading from 0.2](docs/upgrading-0.3.md) | Additional changes before deploying the durable Worker |
 
 The sections below are the configuration and API reference.
 
 ## Install and send from Rails
 
-Add version 0.2 to your Gemfile. Existing 0.1 users should follow the [upgrade guide](docs/upgrading-0.2.md), including the coordinated Rails/Worker update:
+Add version 0.4 to your Gemfile. Existing mailbox users should follow the [core upgrade guide](mailbox-kit/docs/upgrading.md). When upgrading from 0.2, also follow the [durable Worker upgrade guide](docs/upgrading-0.3.md):
 
 ```ruby
-gem "cloudflare-email", "~> 0.2.0"
+gem "cloudflare-email", "~> 0.4.0"
 ```
 
 ```sh
@@ -209,6 +229,11 @@ Equivalent environment names are `CLOUDFLARE_MANAGEMENT_TOKEN` and `CLOUDFLARE_I
 1. Add the receiving subdomain, for example `in.example.com`, in **Email Routing → apex domain → Settings → Subdomains**. This is a separate onboarding step from sending.
 2. Deploy the environment's Worker and create its route:
 
+First create the private R2 bucket and Queue, then deploy the generated Wrangler
+configuration using the [durable setup guide](templates/worker/docs/durable-inbound.md).
+The Ruby task below updates that provisioned Worker while preserving its bindings.
+It refuses a missing bucket/queue binding or recovery schedule before changing code.
+
 ```sh
 RAILS_ENV=production bin/rails cloudflare:email:deploy_worker URL=https://app.example.com/rails/action_mailbox/cloudflare/inbound_emails
 RAILS_ENV=production bin/rails cloudflare:email:provision_route ADDRESS=support@in.example.com
@@ -228,18 +253,18 @@ end
 
 `Cloudflare::Email::Envelope.for(inbound_email)` returns a string-keyed `{"from" => "sender@example.com", "to" => "support@example.com"}` hash, or `nil` when the record has no authenticated envelope (for example, another ingress). The metadata is stored on the raw-email blob before routing jobs enqueue. It does not modify the MIME source. Envelope sender information records the SMTP reverse path; it does not authenticate the human sender. An empty `from` is valid for bounces.
 
-Version 0.2 requires the bundled v2 Worker; missing or v1 signatures are rejected. Coordinate Rails and Worker deployment while ingress is paused. The Worker requires ASCII dot-atom addresses, at most 254 bytes with a 64-byte local part. Quoted local parts, address literals, and internationalized addresses are not supported by this envelope format.
+The bundled Worker uses v2 signatures by default; missing or v1 signatures are rejected. The custom-ingress API also supports opt-in v3 signatures carrying authenticated Worker metadata. See [custom ingestion](docs/custom-ingress.md) and upgrade the Rails receiver before enabling v3 in a custom Worker. When upgrading from v1, coordinate Rails and Worker deployment while ingress is paused. Both envelope versions require ASCII dot-atom addresses, at most 254 bytes with a 64-byte local part. Quoted local parts, address literals, and internationalized addresses are not supported by this envelope format.
 
 Successful ingress storage returns HTTP 200; duplicate storage returns 200 too. The timestamp window limits request age, but is not a one-time replay ledger. Version 2 deduplication includes the exact SMTP recipient, so identical MIME delivered to separate To/Cc/Bcc recipients creates separate inbound records while a retry for the same recipient creates none.
 
-The Worker has a 15-second Rails request timeout and rejects redirects. Non-2xx responses, timeouts, and network failures call `message.setReject`. There is no durable buffering of inbound email: an application outage can reject mail. Storage acceptance does not guarantee later mailbox-job success. Monitor Rails jobs and Cloudflare Worker logs.
+The Worker has a 15-second Rails request timeout and rejects redirects. Its default [durable inbound path](templates/worker/README.md#durable-inbound-delivery) saves messages in R2 before acceptance, then retries Rails handoffs through Queues and scheduled recovery. Provision the resources before deploying. `INBOUND_DELIVERY_MODE=direct` selects the single-attempt fallback, which can reject mail during an outage; existing retained mail keeps recovering. Rails storage acceptance does not guarantee later mailbox-job success. Monitor Rails jobs and Cloudflare Worker logs.
 
 ### Local development and deployment
 
-Start Rails, then:
+For a simple development tunnel, use the explicit direct fallback. Start Rails, then:
 
 ```sh
-bin/rails cloudflare:email:deploy_worker
+INBOUND_DELIVERY_MODE=direct bin/rails cloudflare:email:deploy_worker
 bin/rails cloudflare:email:dev
 ```
 
@@ -247,7 +272,7 @@ The dev task requires `cloudflared`, refuses environments other than development
 
 For a custom installer `--worker-dir`, pass `SCRIPT=custom-directory/src/index.js` to the Ruby `deploy_worker` task. The installer prints the corresponding command.
 
-Ruby deployment and Wrangler use matching names: `cloudflare-email-ingress-development`, `-staging`, and `-production`. The optional Wrangler path requires Node 22.12+ (or a supported newer version):
+Ruby deployment and Wrangler use matching names: `cloudflare-email-ingress-development`, `-staging`, and `-production`. Initial durable infrastructure deployment uses Wrangler and requires Node 22.12+ (or a supported newer version):
 
 ```sh
 cd cloudflare-worker
@@ -312,6 +337,8 @@ Cloudflare's current [header documentation](https://developers.cloudflare.com/em
 | `account_id`, `api_token` | Required |
 | `base_url` | `https://api.cloudflare.com/client/v4` |
 | `timeout` | 30 seconds for open/read/write |
+| `total_timeout` | Defaults to `timeout`; bounds one complete HTTP attempt, including headers and streamed body |
+| `max_response_bytes` | 1 MiB for `Client`; 32 MiB for `EventConsumer` queue batches |
 | `retries` | 3 additional attempts |
 | `initial_backoff` | 0.5 seconds, doubling |
 | `max_retry_after` | 60 seconds |
@@ -320,6 +347,14 @@ Cloudflare's current [header documentation](https://developers.cloudflare.com/em
 
 By default, only 429 responses and pre-send connection failures retry. Numeric and HTTP-date `Retry-After` values are honored up to the cap. Read/write timeouts, connection resets, and 5xx responses may occur after acceptance; they raise without automatically resending. Setting `retry_ambiguous: true` restores retries for those failures and can send duplicates.
 
+Responses are streamed with a byte limit, including decompressed content and
+error responses. A total deadline or response-size failure after transmission
+does not prove a send failed: the outbox preserves the ambiguous claim and blocks
+automatic resend. Net::HTTP's implicit retries are disabled. Explicit retries
+and backoff can make a logical call longer than `total_timeout`; queue handlers,
+database transactions and a complete polling run have separate runtime budgets.
+An uncertain queue acknowledgement permits receipt replay, never email resending.
+
 No idempotency key is sent. Reusing Message-ID does not guarantee deduplication or exactly-once delivery. Account for ActiveJob's retry policy too: retrying the whole mailer job can resend even when this client's retries are disabled.
 
 Errors inherit from `Cloudflare::Email::Error`: `ConfigurationError`, `AuthenticationError`, `ValidationError`, `RateLimitError`, `ServerError`, and `NetworkError`. API errors expose `status` and parsed `response`.

data/app/controllers/cloudflare/email/ingress_controller.rb

@@ -1,16 +1,12 @@
-require "cloudflare/email/verification"
+require "cloudflare/email/ingress"
 
 module Cloudflare
   module Email
     # ActionMailbox ingress for Cloudflare Email Worker forwards.
     #
-    # The shipped Worker template signs each forwarded message with HMAC-SHA256
-    # over "v2.{timestamp}.{encoded_envelope}.{raw_body}" and sends:
-    #   X-CF-Email-Timestamp: <unix seconds>
-    #   X-CF-Email-Signature: <hex digest>
-    #   X-CF-Email-Signature-Version: 2
-    #   X-CF-Email-Envelope: <unpadded base64url JSON from/to>
-    # Requests must include the v2 signature and authenticated SMTP envelope.
+    # The default Worker uses v2 authenticated SMTP envelopes; custom Workers
+    # can opt into v3 to authenticate additional provider metadata. Both use
+    # the shared, bounded Ingress verifier before any tenant lookup or storage.
     #
     # Set the shared secret in Rails credentials under cloudflare.ingress_secret
     # (or in the CLOUDFLARE_INGRESS_SECRET env var) and as the Worker secret
@@ -24,45 +20,29 @@ module Cloudflare
           "cloudflare_email.ingress",
           bytes: 0,
         ) do |payload|
-          preflight = Cloudflare::Email::Verification.verify_headers(secret: secret,
-            timestamp: request.headers["X-CF-Email-Timestamp"],
-            signature: request.headers["X-CF-Email-Signature"],
-            version: request.headers["X-CF-Email-Signature-Version"],
-            envelope: request.headers["X-CF-Email-Envelope"])
-          unless preflight == :ok
-            payload[:result] = preflight
-            next head(preflight == :stale ? :request_timeout : :unauthorized)
-          end
-          if request.content_length.to_i > max_email_bytes || raw_body.bytesize > max_email_bytes
-            payload[:result] = :too_large
-            next head(:payload_too_large)
-          end
-          payload[:bytes] = raw_body.bytesize
-          case Cloudflare::Email::Verification.verify(
-                secret:    secret,
-                body:      raw_body,
-                timestamp: request.headers["X-CF-Email-Timestamp"],
-                signature: request.headers["X-CF-Email-Signature"],
-                version: request.headers["X-CF-Email-Signature-Version"],
-                envelope: request.headers["X-CF-Email-Envelope"],
-              )
+          request.body.rewind if request.body.respond_to?(:rewind)
+          result = Cloudflare::Email::Ingress.verify(secret: secret,
+            headers: request.headers, body: request.body,
+            content_length: request.content_length, max_email_bytes: max_email_bytes)
+          payload[:bytes] = result.bytes.to_i
+          payload[:result] = result.status
+          case result.status
           when :stale
-            payload[:result] = :stale
             head :request_timeout
           when :bad_signature
-            payload[:result] = :bad_signature
             head :unauthorized
+          when :too_large
+            head :payload_too_large
           when :ok
             inbound = if defined?(Cloudflare::Email::Mailboxes) && Cloudflare::Email::Mailboxes.enabled?
-              recipient = Cloudflare::Email::Envelope.decode(request.headers["X-CF-Email-Envelope"]).fetch("to")
               begin
-                Cloudflare::Email::Mailboxes.receive(recipient: recipient) { persist_inbound }
+                result.message.receive_into_mailbox!
               rescue Cloudflare::Email::Mailboxes::Unavailable
                 payload[:result] = :unavailable_mailbox
                 next head(:unprocessable_entity)
               end
             else
-              persist_inbound
+              result.message.persist_action_mailbox!
             end
             payload[:result]     = inbound ? :ok : :duplicate
             payload[:message_id] = inbound&.message_id
@@ -73,37 +53,12 @@ module Cloudflare
 
       private
 
-      def persist_inbound
-        envelope = Cloudflare::Email::Envelope.decode(request.headers["X-CF-Email-Envelope"])
-
-        # Commit trusted routing metadata before ActionMailbox's after_create_commit
-        # enqueues routing. Identical MIME for To/Cc/Bcc recipients is independent.
-        checksum = OpenSSL::Digest::SHA256.hexdigest("v2\0#{envelope.fetch('to')}\0".b + raw_body.b)
-        ActionMailbox::InboundEmail.transaction do
-          inbound = ActionMailbox::InboundEmail.create_and_extract_message_id!(raw_body, message_checksum: checksum)
-          if inbound
-            blob = inbound.raw_email.blob
-            blob.update!(metadata: blob.metadata.merge(
-              Cloudflare::Email::Envelope::METADATA_KEY => envelope.merge("version" => 2),
-            ))
-          end
-          inbound
-        end
-      end
-
       # Override ActionMailbox::BaseController's default name inference so
       # `config.action_mailbox.ingress = :cloudflare` gates this controller.
       def ingress_name
         :cloudflare
       end
 
-      def raw_body
-        @raw_body ||= begin
-          request.body.rewind if request.body.respond_to?(:rewind)
-          request.body.read(max_email_bytes + 1).to_s
-        end
-      end
-
       def max_email_bytes
         @max_email_bytes ||= begin
           value = Integer(ENV.fetch("MAX_EMAIL_BYTES", DEFAULT_MAX_EMAIL_BYTES.to_s), 10)

data/app/controllers/cloudflare/email/management/mailboxes_controller.rb

@@ -0,0 +1,9 @@
+require File.join(MailboxKit::ROOT, "app/controllers/mailbox_kit/management/mailboxes_controller.rb")
+module Cloudflare
+  module Email
+    module Management
+      class MailboxesController < MailboxKit::Management::MailboxesController
+      end
+    end
+  end
+end

data/app/controllers/cloudflare/email/management/styles_controller.rb

@@ -0,0 +1,9 @@
+require File.join(MailboxKit::ROOT, "app/controllers/mailbox_kit/management/styles_controller.rb")
+module Cloudflare
+  module Email
+    module Management
+      class StylesController < MailboxKit::Management::StylesController
+      end
+    end
+  end
+end

data/docs/activerecord-tenanted.md

@@ -123,6 +123,52 @@ end
 
 See the [mailbox guide](mailboxes.md) for domain activation, address provisioning, sending, and event replay. Your application still authorizes which organization, mailbox, and message each user can access.
 
+## Account emails without an organization
+
+Password resets and portal invitations can belong to the application rather
+than an organization. If you enabled separate tenant databases, give those
+outbox records an explicitly provisioned, host-reserved database too. Keep the
+business record's organization empty; a storage key is not an organization or
+an authorization grant.
+
+For example, after configuring the adapter above, provision and migrate a
+reserved database through your deployment workflow:
+
+```ruby
+# Run once through trusted provisioning, not during sending or event replay.
+TenantRecord.create_tenant("_system_outbound")
+```
+
+Your own service can select storage consistently for sending and feedback:
+
+```ruby
+module EmailStorage
+  SYSTEM_KEY = "_system_outbound".freeze
+
+  def self.with_outbound_storage(organization_key, &block)
+    # The caller must supply an already-authorized organization key.
+    key = organization_key.nil? ? SYSTEM_KEY : organization_key
+    Cloudflare::Email::Tenancy.with(key, &block)
+  end
+end
+
+EmailStorage.with_outbound_storage(nil) do
+  # Prepare/read/reconcile the system email's saved outbox operation here.
+end
+```
+
+Reserve the key against customer selection, include this database in migrations,
+backups and restoration drills, and use the same selection for receipt replay.
+If your shared business records use another database, retain their own durable
+receipt/projection boundary: a tenant commit and a shared commit are not atomic.
+Replay a committed gem operation rather than sending it again.
+
+Never modify the tenancy adapter to treat every missing context as the system
+database. Missing context must continue to fail closed. Your organization's job
+fan-out should enumerate real organizations, not every database file. Applications
+without configured multi-tenancy can keep ordinary system and organization mail
+in their existing single database; this recipe does not enable tenancy by default.
+
 ## What is verified
 
 The optional CI job boots a real Rails application with `activerecord-tenanted`, runs the gem's tenant migrations in two SQLite databases, and checks identical numeric IDs remain isolated. It also verifies context restoration, refusal to create unknown tenant databases, and GlobalID's missing/wrong-tenant rejection. Separate integration tests exercise mailbox ingress, sending, jobs, and delivery-event replay.

data/docs/architecture.md

@@ -14,7 +14,7 @@ durable infrastructure without copying the reference inbox's models and services
 | Shared event intake, tenant correlation and tenant-aware jobs | Durable queue workers, scheduled recovery and schema rollout to every tenant |
 | Structured/raw sending and ActionMailer transport | Compose UI, recipients and send authorization |
 | `Response#accepted?`, plus individual recipient outcomes | Handle partial acceptance without resending accepted recipients |
-| Authenticated v2 ingress and recipient-scoped deduplication | Map trusted recipient to an authorized mailbox |
+| Authenticated ingress (default v2; opt-in v3 [metadata](custom-ingress.md)) and context-scoped deduplication | Map trusted recipient to an authorized mailbox; apply sender and document policy |
 | `MessageId.normalize` and returned provider IDs | Store conversation membership and scope reply lookups |
 | Queue decoding, validation and ACK | Queue/subscription setup and recurring execution |
 | Optional ActiveRecord event receipts, deduplication and indexed replay | Configure queue polling and receipt retention |
@@ -75,7 +75,15 @@ does not automatically provision domains or deploy infrastructure.
 
 Current limitations are deliberate and visible: no provider exactly-once API,
 no automatic resend of uncertain or rejected operations, no multi-provider-ID
-operation (conflicting IDs require review), and no durable inbound Worker buffer.
+operation (conflicting IDs require review). Direct inbound forwarding can reject
+mail during a Rails outage. The default [durable Worker path](../templates/worker/README.md#durable-inbound-delivery)
+commits raw mail and stable envelope context to R2 before returning successfully.
+Queue handoffs and a scheduled recovery pass retry pending mail; a Rails 2xx
+allows removal from the pending store. Queue expiration does not remove R2 mail.
+This boundary requires durable Rails persistence before 2xx, idempotent replay,
+private R2 storage without expiration of pending objects, and operational
+monitoring. It cannot guarantee acceptance when Cloudflare itself cannot store
+the incoming message.
 A prepared operation can be dispatched using its existing identity after a job
 enqueue failure; sending/unknown operations require evidence-based reconciliation.
 Notifications indicate method execution and may run inside an outer transaction;
@@ -92,4 +100,6 @@ silently impose a marketing subscription model on transactional mail.
 The optional [mailbox module](mailboxes.md) now packages mailbox persistence and
 address management over the existing transport/receipt APIs. It includes a
 [tenant adapter](activerecord-tenanted.md), without adding a tenant library to
-the plain Ruby client. A future inbox UI or starter should consume these APIs.
+the plain Ruby client. The optional [management engine](management-engine.md)
+consumes these same APIs with host-supplied authentication and authorization.
+Full inbox products can continue using them through their own frontends.