cloudflare-email 0.4.0 → 0.4.2

data/docs/verification/2026-09-10.md

@@ -1,175 +0,0 @@
-# Verification report — 2026-09-10
-
-## Result
-
-The local automated checks pass after fixing a defect found only in the actual Workers runtime. This report records the initial local-only phase. A subsequent [live verification pass](2026-09-10-live.md) verified isolated sending, deployed ingress, replies, real LLM processing, and delivery-event redelivery/acknowledgement; it found and fixed a queue decoder bug and confirmed custom Message-IDs are replaced. See that report for current counts and remaining limits.
-
-**Rebulk does not currently dogfood this gem.** Its existing email tests pass, but a test-only switch to the gem exposes four migration blockers. Do not treat those characterization results as production acceptance.
-
-**Additional dogfooding app located and tested:** `cole-robertson/agentic-inbox-rails-full`
-is the Rails/Inertia inbox prototype built in April. [PR #26](https://github.com/cole-robertson/agentic-inbox-rails-full/pull/26)
-initially pinned this gem's 0.2.0 candidate at `a1f80d8` and passed 140 local Rails examples,
-including signed ingress → triage/draft → UI send approval → provider acceptance →
-reply threading. Its copied Worker passes nine tests and a dry-run build. See its
-[application verification report](https://github.com/cole-robertson/agentic-inbox-rails-full/blob/maintenance/cloudflare-email-0.2-dogfood/docs/verification/2026-09-10.md)
-for fixes, existing app maintenance failures, and remaining live-verification limits.
-The smaller `agentic-inbox-rails` demo remains on 0.1.0 and was not changed.
-
-Scope and source snapshots:
-
-- Gem implementation baseline: [9d1cd58](https://github.com/cole-robertson/cloudflare-email/commit/9d1cd581489690c5befbfaadc7f88f3535a3435f), plus this report's accompanying runtime fix and verification scripts.
-- Rebulk: [46db134](https://github.com/Rebulk/rebulk-system/commit/46db134e2722568d09fc1c4139266a937a03eaef), checked out separately for testing. No tracked Rebulk files changed.
-- Ruby 3.4.1 / Rails 8.1.3.1 for the final gem run; Ruby 3.4.5 / Rails 8.1.3.1 for Rebulk. Local runtime: Node 22.23.1, Wrangler 4.131.0 and its bundled workerd.
-
-## Evidence and results
-
-| Layer | Result | What it establishes |
-|---|---|---|
-| Gem suite | **192 tests, 577 assertions, zero failures/errors/skips** | Sending/MIME, retry/error contracts, response outcomes, signing, routing, tasks, events, and three subprocess Rails fixtures |
-| Rails fixture detail | **40 nested tests** across inbound, send-only, and fresh-inbound apps | Actual boot, generators, migrations, credentials, persistence, duplicate acknowledgement, default mailbox routing/job execution, and task/dev behavior; these run inside the three suite wrapper tests |
-| Actual local workerd → Rails | **16 checks passed** | Runtime interoperability, raw MIME/binary integrity, duplicate acceptance, mailbox processing, misconfiguration rejection, redirects, and request timeout |
-| Worker Node tests | **9 tests passed** | Unit behavior, including explicit 302 response handling; complementary to workerd |
-| Packaged distribution | **Isolated Ruby consumer passed; 40 Rails tests / 179 assertions passed** | Build/install of the actual .gem, Base64 dependency without Rails, and all three Rails fixture modes against packaged files |
-| Expanded CI | **[13/13 jobs passed on 4b968f6](https://github.com/cole-robertson/cloudflare-email/actions/runs/34515534609)** | Eleven Ruby/Rails combinations, packaged installation, Worker unit/build/audit, and actual local workerd → Rails |
-| Rebulk existing email suite | **437 examples in 22 files; zero failures/pending/errors outside examples** | Current SMTP-oriented mailers, custom inbound controller/COA flow, email records, retention, retries, and tracking |
-| Rebulk adapter characterization | **6 examples reproduced expected observations** | Actual UserMailer and CSV ReportMailer can use the adapter in a test process; four production migration gaps below remain |
-| Public DNS read | Completed | Apex MX is Google; mail/in/agent/test subdomains resolve to Cloudflare MX. This does not establish Worker route or token configuration |
-
-The gem suite's 192 top-level tests include three process-wrapper tests; the 40 nested Rails tests are reported separately to avoid implying they are counted by Minitest's top-level summary.
-
-### Runtime defect found and fixed
-
-The April-to-0.2 update used `fetch(..., { redirect: "error" })`. Node accepted it, so the unit tests and dry-run bundle were green. Actual workerd rejected that option before contacting Rails.
-
-The Worker now uses `redirect: "manual"` and rejects the returned 3xx response through its non-2xx path. The new runtime test proves a 302 target is never contacted.
-
-The same test:
-
-- Sends a synthetic multipart message through the real local email simulator.
-- Compares the stored raw RFC822 bytes exactly.
-- Verifies an attachment containing all 256 byte values plus binary terminators.
-- Checks a repeated message stores only one record.
-- Executes the real ActionMailbox routing job and checks the mailbox receives the attachment.
-- Checks wrong/missing shared-secret configurations do not store mail.
-- Measures the actual abort of a stalled local ingress: **15.08 seconds** in the final run.
-
-This test uses loopback HTTP and temporary storage. It does not exercise Cloudflare's managed SMTP service, deployed Workers, DNS routing, or sender-provider behavior.
-
-## Was there an old test report?
-
-I found meaningful historical tests, but no preserved, sanitized live-results report:
-
-- Local `2026-04-16-cloudflare-mailer/trial/test/integration/` contains **20 Rails integration tests** across credentials, inbound, instrumentation, outbound, and routing. Outbound uses WebMock; inbound uses local signed requests. These are not live Cloudflare tests.
-- `trial2/app/mailboxes/main_mailbox.rb` contains the signed-Message-ID reply experiment. No reproducible live round-trip assertion script was found alongside it.
-- Both `trial/` and `trial2/` are gitignored and untracked; they were never part of repository CI.
-- The original changelog/README claim live end-to-end testing and a 191-character signed Message-ID. Those are historical assertions, not current verification evidence.
-- A deleted historical `PLAN.md` was a design/checklist, not a results report.
-
-This report and the scripts below are tracked so the current evidence can be rerun.
-
-## Rebulk's actual integration
-
-At the pinned Rebulk commit:
-
-| Area | Current implementation |
-|---|---|
-| Dependency | No `cloudflare-email` entry in Gemfile or Gemfile.lock |
-| Outbound | `:smtp` in [production.rb](https://github.com/Rebulk/rebulk-system/blob/46db134e2722568d09fc1c4139266a937a03eaef/config/environments/production.rb#L72), defaulting to AWS SES; deployment environment can override SMTP settings |
-| Inbound | Custom [email-worker.js](https://github.com/Rebulk/rebulk-system/blob/46db134e2722568d09fc1c4139266a937a03eaef/cloudflare/email-worker.js) → Basic-authenticated `/api/v1/ingest/email` |
-| Routing/business behavior | Org/site routing, sender-authentication metadata, BOL/COA processing, raw R2 archive, ops recovery and backend dispatch |
-| Gem experiments | [cloudflare/README.md](https://github.com/Rebulk/rebulk-system/blob/46db134e2722568d09fc1c4139266a937a03eaef/cloudflare/README.md) distinguishes literal routes under in/agent/test.rebulk.com as separate gem experiments |
-
-The gem's HMAC ActionMailbox ingress is not a drop-in replacement for Rebulk's custom endpoint. Its existing R2 archive, tenant/site dispatch, authenticated-sender policy, recovery behavior, and BOL/COA processing would need an explicit integration design.
-
-No tests referencing Rebulk's Worker source were found in its tracked tree. The 437-example baseline exercises its Rails side; it does not establish that its deployed Worker matches the checked-in source.
-
-### Rebulk migration blockers demonstrated locally
-
-The [portable adapter probe](../../script/rebulk_outbound_probe_spec.rb) loads the gem only into a test process, uses real Rebulk mailers/observers and isolated test databases, and mocks every Cloudflare request.
-
-1. **Provider identity/correlation is wrong.** The preflight CommunicationMessage retains its original local Message-ID after the adapter receives a provider ID. Its provider remains SES/SMTP. The observer finds the record through an internal header, but does not update provider identity. See [CommunicationsEmailTracker](https://github.com/Rebulk/rebulk-system/blob/46db134e2722568d09fc1c4139266a937a03eaef/app/mailers/communications_email_tracker.rb) and [Recorder](https://github.com/Rebulk/rebulk-system/blob/46db134e2722568d09fc1c4139266a937a03eaef/app/services/communications/recorder.rb).
-2. **All-bounced/all-suppressed reports become “sent.”** A normal HTTP-success response is sufficient for Rebulk's observers to mark the report sent and its communication accepted, even when no recipient was delivered or queued. Integrate the per-recipient response/event outcomes before using this provider. See [ReportEmailDeliveryObserver](https://github.com/Rebulk/rebulk-system/blob/46db134e2722568d09fc1c4139266a937a03eaef/app/mailers/report_email_delivery_observer.rb).
-3. **Ambiguous failures lose their special treatment.** Rebulk's [ReportMailer](https://github.com/Rebulk/rebulk-system/blob/46db134e2722568d09fc1c4139266a937a03eaef/app/mailers/report_mailer.rb#L1805) recognizes raw network exception classes. The gem wraps these in `Cloudflare::Email::NetworkError`, so a read timeout moves its report claim back to queued rather than preserving the existing unknown-outcome state.
-4. **Job retries are SMTP-specific.** An exhausted `Cloudflare::Email::RateLimitError` is re-raised without scheduling an application retry. The [retry initializer](https://github.com/Rebulk/rebulk-system/blob/46db134e2722568d09fc1c4139266a937a03eaef/config/initializers/mailer_retry.rb) needs a deliberate Cloudflare policy that distinguishes pre-send/retryable errors from ambiguous delivery.
-
-The probe's green result means it reproduced these observations, **not** that a migration passes acceptance tests. Production dependencies/configuration were not changed.
-
-## Reproduction
-
-### Gem suite and package
-
-From this gem checkout:
-
-```sh
-bundle install
-bundle exec rake test
-bundle exec ruby script/verify_package.rb
-```
-
-The package script builds a temporary .gem, installs it and Base64 into an isolated consumer bundle from local gem caches, then runs the Rails fixtures against extracted packaged files. It requires a preceding `bundle install` and does not publish anything.
-
-### Actual Workers runtime
-
-```sh
-# Node 22+ required
-npm ci --prefix templates/worker
-npm test --prefix templates/worker
-BUNDLE_GEMFILE=gemfiles/local_ingress.gemfile bundle install
-BUNDLE_GEMFILE=gemfiles/local_ingress.gemfile bundle exec ruby script/verify_local_ingress.rb
-```
-
-Set `NODE_BINARY=/absolute/path/to/node` if your PATH points to an older Node. The final local run used the Node 22.23.1 executable explicitly because this host's npm wrapper otherwise selected Node 20.
-
-### Rebulk baseline
-
-Use a separate checkout of the pinned Rebulk commit, never the shared primary clone. With dependencies installed:
-
-```sh
-env -u DATABASE_URL -u RAILS_MASTER_KEY RAILS_ENV=test \
-  NIGHTRAIL_TOKEN= LANTERN_TOKEN= SECRET_KEY_BASE_DUMMY=1 \
-  bundle exec rails db:test:prepare
-
-env -u DATABASE_URL -u RAILS_MASTER_KEY RAILS_ENV=test \
-  NIGHTRAIL_TOKEN= LANTERN_TOKEN= SECRET_KEY_BASE_DUMMY=1 \
-  bundle exec rspec spec/mailers \
-    spec/jobs/mail_delivery_retry_spec.rb \
-    spec/jobs/prune_inbound_emails_job_spec.rb \
-    spec/tasks/retry_failed_mailer_jobs_spec.rb \
-    spec/requests/api/v1/email_ingest_spec.rb \
-    spec/requests/api/v1/email_ingest_coa_flow_spec.rb \
-    spec/models/inbound_email_spec.rb \
-    spec/models/report_email_spec.rb \
-    spec/models/organization_email_domain_spec.rb \
-    spec/services/communications/recorder_spec.rb
-```
-
-Observed: seed **46556**, 437 examples, 0 failures, 0 pending; 51.88 seconds of examples plus 9.91 seconds loading.
-
-The separate adapter probe's header documents its commands. Reserve `TEST_ENV_NUMBER=9` exclusively for that probe; never run another process against the same primary/tenant test databases. The adapted probe passed its six characterization examples with seed **45808**.
-
-### Public DNS observation
-
-A read-only MX lookup returned:
-
-- `rebulk.com`: Google's five Workspace MX hosts.
-- `mail.rebulk.com`, `in.rebulk.com`, `agent.rebulk.com`, `test.rebulk.com`: `route1/2/3.mx.cloudflare.net` with priorities 30/61/91.
-
-No DNS records were changed. These answers do not identify which Worker a literal address reaches or prove sending-domain verification.
-
-## Initial live acceptance gate (see subsequent live report)
-
-Do not describe the release as live-verified until these have evidence from a controlled account and confirmed recipient inbox:
-
-| Check | Required evidence |
-|---|---|
-| Account, sending domain, tokens | Read-only confirmation of the exact account/domain and least-privilege token capabilities |
-| Outbound structured + raw MIME | Provider response and received synthetic message; HTML/text, attachment hash, cc/bcc behavior, provider ID |
-| Inbound deployed Worker | Dedicated exact test address reaches an isolated verification Worker and Rails app; one stored/processed message |
-| Reply threading | Delivered raw Message-ID and returned reply headers; confirm whether custom signed IDs survive or use provider-ID correlation |
-| Delivery events | Actual domain-scoped Queue subscription, observed event, durable handler result, successful acknowledgement, duplicate-safe processing |
-| Environment isolation | Confirm exact Worker names/addresses and secrets; no production route changes |
-| Cleanup | Remove only newly created verification resources; retain sanitized results |
-
-Proposed live scope for approval: a dedicated address under the already-existing `test.rebulk.com`, a uniquely named verification Worker/Queue, a temporary test Rails app, and a mailbox explicitly confirmed by the owner. Inspect existing address routes first; do not replace Rebulk's zone catch-all or existing experimental routes.
-
-These steps send real email and may create/deploy isolated resources, so the target mailbox/account and live scope must be confirmed before execution. No real email, Cloudflare deployment, Queue consumption, secret decryption, or production changes occurred during this verification. Public DNS lookup was the only live infrastructure inspection.

data/docs/verification/2026-09-11-custom-ingress.md

@@ -1,49 +0,0 @@
-# Custom ingress and routing diagnostics verification
-
-Scope: upstream gem integration tools informed by Rebulk's existing ingestion
-pipeline. This report covers local synthetic verification, not a Rebulk rollout.
-
-## Results
-
-| Check | Result |
-| --- | --- |
-| Full Ruby suite, Ruby 3.4.1 / Rails 7.2, 8.0, 8.1 | Each: 257 tests, 916 assertions, no failures/errors/skips |
-| Shared ingress unit tests | 12 tests, 98 assertions; independent Node/Ruby v3 binary/Unicode vector, tampering, metadata bounds, short streams, immutable results, retry identity |
-| Custom Rails endpoint | 5 integration tests, 37 assertions; separate SQLite tenant databases, policy before persistence, durable signed metadata and retries |
-| Built-in Rails endpoint | V3 persistence before routing enqueue, binary preservation, retries and unsigned v2 metadata rejection; covered in the full suite |
-| Read-only routing diagnostics | 27 tests, 50 assertions; mocked Cloudflare configuration, exact-domain DNS, rule selection, ambiguous/inaccessible responses and pagination |
-| Worker | 45 tests pass; Wrangler dry-run succeeds |
-| Packaged consumer | Isolated plain Ruby install and packaged Rails installation/ingress fixtures pass |
-| Local workerd → Rails | Real local forwarding, Bcc routing, attachment preservation, wrong/missing secrets, redirects and timeout handling pass |
-
-Independent reviews found two verifier issues: a readable stream can return
-short chunks, and HMAC must use the timestamp's exact transmitted bytes. Both
-were corrected and covered by regression tests. Freshness still parses decimal
-seconds; existing bundled Worker timestamps are unchanged.
-
-## Reproduce
-
-```sh
-BUNDLE_GEMFILE=gemfiles/rails_7_2.gemfile bundle exec rake test
-BUNDLE_GEMFILE=gemfiles/rails_8_0.gemfile bundle exec rake test
-BUNDLE_GEMFILE=gemfiles/rails_8_1.gemfile bundle exec rake test
-bundle exec ruby script/verify_package.rb
-BUNDLE_GEMFILE=gemfiles/local_ingress.gemfile bundle exec ruby script/verify_local_ingress.rb
-npm --prefix templates/worker test
-npm --prefix templates/worker run check
-```
-
-Use Node 22 for the Worker and local forwarding checks.
-
-## Limits
-
-No Rebulk application code, live DNS, Worker deployment, inbox activation, R2
-archive, or gem publication was changed. The local workerd test exercises the
-default v2 transport; opt-in v3 is covered by Worker tests, an independent shared
-signature vector, and real Rails integration tests, not deployed Cloudflare mail.
-
-Routing diagnostics inspect provider configuration through mocked API tests.
-A passing configuration snapshot does not establish public DNS propagation,
-complete SPF evaluation, Worker application behavior, or live delivery. Signed
-metadata authenticates the forwarding integration's assertions; the host still
-owns original-sender trust, held-message policy, and business processing.

data/docs/verification/2026-09-11-extraction.md

@@ -1,32 +0,0 @@
-# Preproduction cleanup and reusable event receipts — September 11, 2026
-
-This pass removes v1 ingress and SecureMessageId, adds optional ActiveRecord event
-receipts, and extracts provider acceptance, message-ID normalization and delivery
-ordering helpers. See [architecture](../architecture.md) for the implemented
-boundary and the next outbound-ledger extraction.
-
-## Local checks
-
-| Check | Result |
-| --- | --- |
-| `bundle exec rake test`, Ruby 3.4.1 / Rails 8.1.3.1 | 189 tests, 635 assertions, no failures/errors/skips |
-| Durable event adapter subprocess included in suite | 13 SQLite tests, 56 assertions |
-| `bundle exec ruby script/verify_package.rb` | Isolated Ruby consumer and Rails package checks passed; 48 tests, 235 assertions |
-| `script/verification/install_upgrade.rb` under Ruby 4 / Rails 8.1 | 16 checks passed, including v1 rejection and v2 inbox routing |
-| Local actual workerd → Rails | 19 checks passed using Node 22.23.1 |
-
-Receipt tests exercise the generated migration, account-scoped database uniqueness,
-concurrent duplicate insertion, changed-payload rejection, commit-before-ACK,
-failed persistence preventing ACK, replay, savepoint/handler rollback, and explicit
-handler outcomes. Plain gem loading is checked without ActiveRecord.
-
-The Worker run verifies authenticated SMTP metadata, unchanged MIME and all 256
-binary byte values, same-recipient deduplication, separate Bcc recipient records,
-mailbox-job execution, secret mismatch, redirect rejection, and a real 15-second
-timeout. The first invocation found Node 20 on PATH and failed before Worker
-startup; rerunning with explicit installed Node 22.23.1 passed.
-
-These are local checks using synthetic mail, SQLite and controlled HTTP responses.
-No email was sent, no Worker deployed, and no RubyGem published in this pass.
-PostgreSQL locking and live delivery using this new adapter have not been verified.
-Earlier live reports remain evidence for their dated revisions only.

data/docs/verification/2026-09-11-outbound-ledger.md

@@ -1,60 +0,0 @@
-# Shared outbound ledger verification — September 11, 2026
-
-The optional Rails layer now owns immutable MIME preparation, account-scoped
-operation keys, committed send claims, recipient acceptance evidence, provider
-event projection, and audited reconciliation. The reference inbox consumes these
-tables and services rather than keeping its own transport ledger.
-
-## Local results
-
-| Check | Result |
-| --- | --- |
-| Gem suite, Ruby 3.4.1 / Rails 8.1.3.1 | 191 tests, 637 assertions, no failures/errors/skips |
-| Outbox subprocess included in suite | 21 SQLite tests, 112 assertions |
-| Mail snapshots, jobs, event projection subprocess | 9 SQLite tests, 45 assertions |
-| Existing receipt subprocess | 13 SQLite tests, 56 assertions |
-| Actual PostgreSQL 15 verifier | 9 tests, 45 assertions |
-| Packaged isolated Ruby + Rails install/ingress + outbound checks | 57 tests, 280 assertions; all passed |
-
-The top-level gem counts include subprocess assertions, not their individual
-inner assertions. PostgreSQL 16 verification is added to CI. The PostgreSQL
-driver remains an optional test dependency; the gem has no new runtime database
-or job dependencies for plain Ruby users.
-
-## Failure and concurrency coverage
-
-- Eight concurrent identical operations produce one stored snapshot and one
-  provider request. Conflicting snapshots cannot overwrite the winner.
-- Independent operations reach the controlled provider concurrently.
-- A real SIGKILL after the durable claim leaves the operation blocked after
-  restart. A real PostgreSQL backend termination plus simulated provider timeout
-  also preserves the non-retryable claim.
-- Acceptance followed by database failure does not permit another send.
-- Partial acceptance never resends the whole batch. Unknown recipients can be
-  reconciled independently while known lifecycle states remain intact.
-- Malformed IDs and conflicting per-recipient provider IDs become uncertainty;
-  a valid common ID on a later recipient entry is retained.
-- Event-before-response, duplicate callbacks, concurrent out-of-order events,
-  terminal guards, account mismatch and ambiguous IDs are exercised.
-- Application callback failure rolls back product and recipient writes while
-  retaining the receipt; replay applies it. A send-job retry repairs failed
-  product projection without another provider request.
-- MIME includes a binary attachment containing all 256 byte values and a hidden
-  Bcc envelope recipient. Jobs serialize only the account and operation key.
-- Reconciliation requires actor/reason/evidence and legal unresolved transitions.
-  Sending reconciliation requires a stopped sender confirmation and a minimum
-  claim age. Generated migrations refuse to delete safety evidence on rollback.
-
-## Boundaries
-
-HTTP acceptance and lifecycle payloads use controlled local fixtures. This pass
-does not send live mail, deploy a Worker, publish RubyGems, or prove inbox placement.
-Earlier Cloudflare live reports describe their own revisions. Provider-ID
-correlation assumes Cloudflare assigns unique IDs; pre-existing duplicate matches
-are retained as unmatched for review. The network and database remain separate
-transactions, and the system does not claim exactly-once provider delivery.
-
-The reference inbox has separate HTTP, browser, process-recovery and import
-verification recorded in its `docs/verification/2026-09-11-outbox.md`. Historical
-records preserve available content and audit data; reconstructed imported MIME
-is explicitly marked and is not claimed to reproduce historical wire bytes.

data/docs/verification/2026-09-11-security.md

@@ -1,76 +0,0 @@
-# Security review — 2026-09-11
-
-Reviewed the 0.2.0 gem at baseline `bd83e067938d5c8df5a7a2ced2cf2a74c3f58e06`
-and applied the hardening described below on `security/gem-hardening`.
-This was a defensive source review, dependency audit and local verification.
-No live penetration testing was performed and no production compromise was
-demonstrated. Prior live test reports describe different revisions.
-
-## Findings and fixes
-
-Priorities are contextual review judgments, not CVSS scores.
-
-| Priority | Finding and prerequisite | Remediation |
-| --- | --- | --- |
-| High | The development tunnel exposed the full Rails origin when enabled, including routes unrelated to email. | Force a dedicated origin Host and install a first-position development middleware that permits only the ingress POST. Refuse to start the tunnel unless the running server has the guard. |
-| High | The old Rails 7.1 test stack resolved dependencies with 12 advisory hits, including ActiveStorage CVE-2026-66066. Application exposure depends on its resolved dependencies and feature use. | Remove that unsupported matrix variant; raise Rails/SQLite test floors and audit resolved Ruby matrix locks in CI. Applications must update their own dependencies. |
-| Medium | Inbound MIME was read without an application bound, allowing large requests/messages to consume memory. Upstream limits determine reachability. | Default 25 MiB bound in Rails and Worker, declared-size checks and bounded stream reads. Reject malformed/stale signing headers before Rails reads the body. Full HMAC verification still follows the read. |
-| Medium | Operator-configured remote HTTP endpoints could transmit credentials or mail without TLS. | Require HTTPS for API and ingress endpoints, except literal loopback development hosts. Validate deploy configuration before remote mutations. Endpoint configuration remains trusted. |
-| Medium | Delivery-event validation omitted important field types; original receipt identity/payload could be changed through ordinary model updates. Requires malformed queue input or application writes. | Validate identifiers, recipient, timestamp, terminal boolean and optional detail objects; mark receipt evidence fields read-only. Preserve unknown schema-1 future event types without projecting an unknown lifecycle state. |
-| Low | Client inspection, retry warnings and generated mailbox logs could disclose tokens or private provider/mail details. | Redact client inspection and remove sensitive fields from those default logging paths. Raw errors/responses remain available to applications. |
-| Low | Provider acceptance helpers treated some malformed success fields or message IDs permissively. | Require explicit boolean success when present, successful HTTP status, valid string IDs and array-shaped recipient outcomes. |
-
-Reviewed HMAC v2/envelope handling, recipient-scoped deduplication, transport
-retries, event account/domain checks and ACK ordering, durable outbox claims,
-tenant/account correlation, evidence storage, deployment/generator behavior,
-package contents and CI permissions. No additional concrete authentication or
-claim-bypass finding was established in these paths; this is not proof that
-all defects are absent.
-
-## Verification
-
-Final Ruby behavior checks used Ruby 3.4.1 and Rails 8.1.3.1:
-
-- `bundle exec rake test`: **205 tests, 751 assertions**, no failures/errors/skips.
-  Includes real Rails subprocesses, SQLite receipts/outbox and development guard.
-- Worker `npm test`: **28 tests passed**, Node 22.23.1.
-- Worker `npm run check`: Wrangler deployment dry-run passed.
-- `script/verify_package.rb`: isolated plain Ruby consumer, packaged Rails
-  installation/ingress and durable outbound checks passed.
-- `script/verify_local_ingress.rb`: actual local workerd-to-Rails verification
-  passed, including exact MIME/binary attachment preservation, trusted envelope,
-  deduplication and separate recipients, routing, invalid/missing credentials,
-  refused redirects and a stalled upstream aborted after 15 seconds.
-  No real email was sent and no Worker was deployed by this run.
-- `bundler-audit 0.9.3`: no known vulnerabilities in the six supported locally
-  resolved lockfiles (default, local ingress, PostgreSQL, Rails 7.2/8.0/8.1).
-  Advisory database commit: `93b32f641f84282183ce58ab1d7204bee50885bd`.
-- `npm audit --audit-level=low`: **zero known vulnerabilities**.
-- `git diff --check`: passed.
-
-Ruby lockfiles are not committed; audits describe these resolutions and the
-advisory database at review time. CI audits newly resolved Ruby matrix stacks.
-PostgreSQL concurrency execution and the broader Ruby matrix are delegated to
-the PR's CI; their results should be checked separately from the local results.
-
-## Remaining boundaries and rollout
-
-See [SECURITY.md](../../SECURITY.md) for application and deployment controls.
-Upstream request buffering, rate limiting and read deadlines remain external.
-Mail rendering, malware scanning, tenant authorization, encryption and retention
-are application responsibilities. Queue write access is an authenticity boundary;
-account labels are not signatures. Read-only ActiveRecord attributes do not
-prevent privileged SQL changes. Inbound deduplication intentionally keys identical
-MIME by SMTP recipient, retaining the first authenticated envelope sender.
-
-The development Host guard restricts routes, but the allowed ingress still runs
-inside the development application: safe error handling and test-only data are
-required. CI action references use version tags rather than immutable commits;
-pinning them is additional supply-chain hardening still available.
-
-These changes are not yet a RubyGems release or a deployed Worker upgrade. The
-dogfood inbox has not been repinned or live-tested against this security branch.
-Rollout requires updating the gem revision, redeploying the Worker, aligning any
-`MAX_EMAIL_BYTES` override, updating application dependencies and restarting Rails
-before opening a development tunnel. Do not equate the earlier dogfood results
-with verification of this revision in a deployed application.

data/docs/verification/2026-09-11-tenant-mailboxes.md

@@ -1,75 +0,0 @@
-# Optional mailboxes and tenant support — 2026-09-11
-
-Implementation source: `4273c5ac10cb87d5e5610acc6a4e69c55d94a42f`.
-The guides and installation pin may receive subsequent documentation-only updates.
-
-## Implemented
-
-- Explicit optional tenant adapter and configurable model base for the existing
-  outbox/receipt models and new tenant mailbox models. Plain Ruby remains independent.
-- Shared receiving-domain directory and tenant mailboxes, aliases, owner references,
-  lifecycle, inbound memberships, read/archive state and explicit purge.
-- Full HMAC verification before recipient-to-tenant resolution, followed by
-  same-connection ActionMailbox/ActiveStorage persistence and membership storage.
-- Scoped mailbox sender checks and identity-only send jobs using the existing
-  immutable outbox, callbacks, reconciliation and conservative retry behavior.
-- Shared event intake before ACK, account/message/recipient correlation to a
-  tenant outbox, tenant commit before shared completion, and bounded recovery jobs.
-- Tenant serialization before framework GlobalID lookup; missing/conflicting
-  tenant metadata rejected. Managed raw mail retained against normal incineration.
-- Composed generator with separate tenant/shared migration paths and optional
-  `activerecord-tenanted` integration guide/bundle/CI job.
-
-## Local verification
-
-Ruby 3.4.1 / Rails 8.1.3.1 unless noted:
-
-| Check | Result |
-| --- | --- |
-| Full `bundle exec rake test` | 212 tests, 758 assertions, no failures/errors/skips |
-| Tenant connection and job subprocess | 11 tests, 54 assertions; physical SQLite shards with overlapping IDs, host-only framework job capture and context restoration |
-| Default job-context subprocess | 3 tests, 7 assertions; ordinary untagged jobs preserved without database tenancy |
-| Mailbox service subprocess | 16 tests, 92 assertions; two fixed SQLite tenant pools plus shared directory |
-| Shared event subprocess | 8 tests, 28 assertions; also checked on Rails 7.2 |
-| Real Rails mailbox ingress subprocess | 4 tests, 29 assertions; signed recipient routing, raw storage, jobs, aliases, deduplication, unavailable destinations, retention and purge |
-| Actual `activerecord-tenanted` 0.8 integration | 3 tests, 23 assertions; real tenant provisioning/migrations, isolation, context and GlobalID checks |
-| Generator checks | Fresh single-DB and separate shared/tenant SQLite installs, migration ordering and initializer syntax |
-| Packaged gem | Isolated Ruby consumer; Rails install/ingress/outbox checks; new tenant ingress, jobs, retention and all mailbox migrations from extracted package |
-| Local workerd → Rails | Existing real runtime fixture passed, including raw bytes, routing, duplicates, invalid credentials, redirects and timeout |
-
-Top-level test totals include subprocess wrapper assertions; detailed subprocess
-counts above describe their internal checks and are not additional top-level tests.
-The service suite includes concurrent claims producing one provider request,
-callback rollback, retry/recovery without resending, reconcile rollback, pagination,
-suspension after enqueue, caller operation-key isolation and sender/account checks.
-Event tests include event-before-response, conflicting identities, cross-tenant
-correlation ambiguity, tenant-commit/shared-failure replay, and callback rollback.
-
-The optional tenant dependency resolution passed bundler-audit. CI additionally
-runs the supported Ruby/Rails matrix, PostgreSQL outbox checks and Worker checks.
-Check the PR's CI for results on its latest revision.
-
-## Operational boundaries
-
-No production Worker, domain/DNS, inbox or Rebulk deployment changed. No real
-email was sent by these checks. The new Worker-to-mailbox path uses the existing
-v2 signature contract; live customer subdomain provisioning was not exercised.
-Rebulk's existing ingest/communication records and sender-authentication policy
-still require a separate, explicit application adoption project.
-
-Directory activation records authorized operator evidence, not independent
-domain verification. Application permissions select tenant and mailbox access;
-raw ActiveRecord and administrative directory methods are privileged interfaces.
-Database keys and queue payloads must come from trusted application state.
-
-Framework records must share the configured tenant connection. Drain old
-ActionMailbox/ActiveStorage jobs before enabling database tenancy because old
-payloads without the new metadata cannot safely be guessed. Mailbox memberships
-retain raw mail until explicit purge, so applications must define a retention
-policy and monitor storage usage.
-
-Queue intake and tenant projection use separate commits with idempotent recovery,
-not a distributed transaction. Schedule polling, shared replay and per-tenant
-recovery. Unknown provider outcomes stay blocked; no exactly-once guarantee or
-automatic resend is added. Existing outbox PostgreSQL behavior remains covered;
-the new mailbox/tenant integration's direct database evidence is SQLite.

data/docs/verification/2026-09-12-destination-context.md

@@ -1,46 +0,0 @@
-# Destination context and email persistence verification
-
-Scope: standalone accepted-address resolution and destination context yielded
-from the existing persisted receive path. No Rebulk deployment or gem release.
-
-## Results
-
-- Full suites on Ruby 3.4.1 with Rails 7.2, 8.0 and 8.1: each passed with
-  257 top-level tests and 916 assertions. These include subprocess integration
-  fixtures whose internal assertions are not included in that top-level count.
-- The standalone service fixture uses two real SQLite tenant databases with
-  colliding mailbox IDs and no ActionMailbox loaded. It verifies host-owned
-  binary-email persistence, immutable destinations, aliases, inactive records,
-  nested context restoration, host exceptions and missing-tenant refusal without
-  creating a database. Lookup itself creates no mailbox membership.
-- The custom Rails ingress fixture verifies saved raw MIME and signed metadata,
-  mailbox membership, and a host business link created from the destination.
-  Routing jobs execute in the correct tenant after commit. Retries do not
-  duplicate the linked records. A host write failure rolls back the email and
-  membership and schedules no routing job.
-- Existing callbacks remain supported, including strict zero-argument lambdas.
-- Packaged plain Ruby and Rails consumer checks pass, including mailbox ingress,
-  routing and existing retention behavior.
-- Independent review found no remaining blockers. A callback arity compatibility
-  issue was fixed and covered before completion.
-
-## Reproduce
-
-```sh
-BUNDLE_GEMFILE=gemfiles/rails_7_2.gemfile bundle exec rake test
-BUNDLE_GEMFILE=gemfiles/rails_8_0.gemfile bundle exec rake test
-BUNDLE_GEMFILE=gemfiles/rails_8_1.gemfile bundle exec rake test
-bundle exec ruby script/verify_package.rb
-```
-
-## Boundaries
-
-Destination context is a lifecycle snapshot, not host authorization or a durable
-processing claim. Applications still validate owners and sender policy and make
-downstream work idempotent. The host owns custom-store transactions; `receive`
-preserves the existing shared tenant transaction for ActionMailbox persistence.
-Neither API makes cross-database or external object-store operations atomic.
-
-Managed mailbox memberships protect raw email from automatic incineration;
-deliberate purge, backups and host-reference cleanup remain application policy.
-These local tests do not verify Rebulk's actual queues, sender policy or archive.

data/docs/verification/2026-09-13-action-mailbox-core.md

@@ -1,96 +0,0 @@
-# Action Mailbox composition verification
-
-## Independent review follow-up
-
-The independent architecture review of `63660eb` confirmed the Rails/core/provider
-split and reproduced a missing inbound membership index with SQLite's query planner.
-The follow-up adds that index to both installers and supplies `mailbox_kit:upgrade`
-for existing schemas. The generator fixture verifies indexed lookup, existing
-membership preservation and repeat application. It passes 4 tests / 27 assertions.
-
-Cloudflare configuration now delegates shared validation to the core, and its
-session behavior is an explicit integration module. Handler overrides retain
-their existing extension point. The short core README links to packaged
-integration and upgrade guides.
-
-After these changes, the full suite passes 289 tests / 1,151 assertions. Package
-verification passes for Rails-free Cloudflare, packaged ingress/outbound/tenancy,
-and an independent Rails consumer without Cloudflare in its bundle.
-
-This is local/package verification, not a Rebulk production rollout. Automatic
-model-owner lifecycle bindings and a universal outbound adapter framework remain
-outside this change. Existing application acceptance, ownership and business
-processing claims must be retained.
-
-Mailbox Kit now treats `ActionMailbox::InboundEmail` as the original email record.
-The kit's `Message` remains an inbox membership with read/archive state; no new
-raw-email table, parser, routing job or processing-status model was introduced.
-
-## Verified behavior
-
-- `Mailboxes.receive(recipient:, source:)` resolves the trusted receiving scope
-  before Rails persistence, and attaches the existing record on source replay.
-  Identical source in two inboxes of one tenant produces one Rails email, two
-  memberships and one routing job. Read state remains independent per inbox.
-- Identical source in different tenants sharing a database produces distinct
-  Rails records/jobs. `Session#attach` rejects a row already associated with a
-  different tenant, and resolves IDs only inside the selected connection.
-- `Session#attach(recipient:, inbound_email_id:)` supports already-stored Rails
-  mail. It is idempotent per mailbox/email, preserves alias reservations and
-  refuses suspended addresses or missing records.
-- The stock Rails Postmark ingress was exercised through HTTP in the isolated
-  Rails fixture. Duplicate webhook payloads produced one Rails email; explicit
-  host-authorized attachment created its inbox membership without reprocessing.
-- Cloudflare retains its prior authenticated envelope/metadata identity and
-  stable Message-ID fallback. Its controller uses `receive_into_mailbox!` and
-  repairs missing membership on replay without re-enqueueing Rails routing.
-  The older `persist_action_mailbox!` still returns nil on duplicate delivery.
-- Rails' `incinerate = false` prevents automatic cleanup scheduling without a
-  membership. With normal cleanup enabled, aged processed unassociated mail is
-  removed while inbox-associated mail survives. The guard uses Rails' public
-  inbound-email load hook and the same row lock as attachment and purge.
-- Removing one of two memberships preserves the shared raw email; removing the
-  last through explicit purge removes it. Failed membership persistence rolls
-  back Rails database records and prevents a routing enqueue.
-- PostgreSQL deliveries were synchronized at Rails creation to force a unique
-  conflict. Both calls completed with one inbound record, one membership, one
-  Active Storage blob record and one routing job. A savepoint rollback keeps the
-  losing transaction usable before looking up the winning record.
-
-## Checks
-
-- Full Ruby suite: 289 top-level tests, 1,151 assertions passed. Integration
-  subprocesses exercise the additional Rails behavior rather than inflating these
-  top-level counts.
-- `script/verify_package.rb`: both gem archives built; Rails-free Cloudflare
-  consumer, packaged Cloudflare integration and independent core-only Rails
-  consumer passed. The independent bundle contains no Cloudflare gem.
-- PostgreSQL inbound suite: 25 tests, 273 assertions passed on a disposable local
-  PostgreSQL 15 instance. CI runs the same suite against PostgreSQL 16 alongside
-  the existing outbox tests.
-- SQLite core/compatibility, separate-tenant ingress and custom ingress regression
-  suites were exercised locally. CI covers the supported Ruby/Rails matrix.
-
-Run the PostgreSQL check only against a disposable database:
-
-```sh
-BUNDLE_GEMFILE=gemfiles/postgres.gemfile \
-POSTGRES_TEST_URL=postgres://localhost/cloudflare_email_test \
-bundle exec ruby script/verify_postgres_inbound.rb
-```
-
-The script creates a unique schema and drops that schema when its fixture exits.
-
-## Limits
-
-The Postmark test is a fixed, authorized single-database route, not a live
-Postmark deployment or a complete dynamic-tenant provider adapter. The caller
-must authenticate ingress and authorize the envelope recipient and inbound ID;
-MIME To/X-Original-To headers are not tenant entitlement. Tenant selection after
-ingress cannot relocate raw mail already persisted to another database.
-
-Raw blob uploads and external side effects are not made transactional by Active
-Record. This check does not establish exactly-once business effects, provider
-outage recovery, lost-job recovery, or live delivery. Existing Cloudflare durable
-transport remains responsible for its outage/retry behavior. Owner lifecycle
-macros and a general outbound adapter framework are separate work.