Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Harden the relay plan against review

Damian Legawiecd22cb183af0c
diff --git a/docs/plans/6.1-marketplace-message-relay.md b/docs/plans/6.1-marketplace-message-relay.md
index a4647979ac..57c2fcdc79 100644
--- a/docs/plans/6.1-marketplace-message-relay.md
+++ b/docs/plans/6.1-marketplace-message-relay.md
@@ -52,23 +52,34 @@ already carrying the marketplace core.
off it. A per-message alias would multiply the addresses a leak could
expose and give the buyer a different reply-to every time.
-4. **A thread is bound to an order and expires with it.** Relay is for
+4. **The thread's own relay domain is stored on it, not read live.** A store
+ that changes its relay domain would otherwise orphan every alias already
+ in the wild — the buyer replies to an address the resolver no longer
+ recognises. The thread records the domain it was opened under, and
+ inbound accepts a token against the domain it was issued for.
+
+5. **Expiry is a time, and inbound enforces it.** `closes_at` is what closes
+ a thread, not a `status` column that something has to remember to write.
+ Inbound checks the clock; a job flipping statuses is a convenience for
+ the UI, never the gate.
+
+6. **A thread is bound to an order and expires with it.** Relay is for
"where is my parcel", not a general channel — it opens when the order is
placed and closes a fixed window after the order is fulfilled or canceled.
An alias that never expires is a permanent forwarding address to a
customer's inbox.
-5. **Inbound is provider-agnostic.** Action Mailbox's own ingresses
+7. **Inbound is provider-agnostic.** Action Mailbox's own ingresses
(Mailgun, Mandrill, Postmark, SendGrid, and the generic `relay` for a
self-hosted MTA) are the supported surface. Spree registers a mailbox and
documents the ingress choice; it does not wrap or prefer one provider.
-6. **The relay is optional and off by default.** A store preference, and an
+8. **The relay is optional and off by default.** A store preference, and an
installation that has not configured inbound mail simply does not offer
it — the seller order keeps the shipping phone it already has. Nothing in
fulfillment may depend on the relay existing.
-7. **Messages are stored, not merely forwarded.** The marketplace is the one
+9. **Messages are stored, not merely forwarded.** The marketplace is the one
who has to answer "what did the seller tell my customer" in a dispute.
A forward-only relay leaves the operator with nothing to look at.
@@ -77,27 +88,44 @@ already carrying the marketplace core.
### Models
- `Spree::MessageThread` — `store_id`, `order_id`, `seller_id`, `token`
- (`has_secure_token`), `status` (`open` | `closed`), `closes_at`.
-- `Spree::Message` — `message_thread_id`, `sender_type` (`customer` |
- `seller` | `operator`), `sender_id`, `body`, `delivered_at`.
+ (`has_secure_token`), `relay_domain`, `closes_at`. Unique on `token`, and
+ unique on `(order_id, seller_id)` so a second thread cannot open for a pair
+ that already has one.
+- `Spree::Message` — `message_thread_id`, `store_id`, `sender_type`
+ (`customer` | `seller` | `operator`), `sender_id`, `body`,
+ `inbound_message_id` (unique, nullable), `delivered_at`.
-Both `Spree::SingleStoreResource`. `status` is a plain `has_status`, moved by
-workflows, per `6.0-service-workflows.md` — no state machine.
+Both `Spree::SingleStoreResource`, so both carry `store_id`.
+
+`inbound_message_id` is the sender's `Message-ID`: a provider that retries a
+webhook must not deliver the same reply twice, and a unique index is the only
+thing that actually holds under a retry.
+
+Note the order the thread binds to is the **seller's child order**, not the
+order group — a basket spanning several sellers is several orders, and a
+thread that spanned them would show one seller another seller's buyer.
### Outbound
-`Spree::MessageMailer` sends the body to the counterparty with
-`reply_to: "#{thread.token}@#{store.preferred_relay_domain}"`. The `from` is
-the marketplace's own address, as every other Spree email is.
+`Spree::MessageMailer` sends the body to the counterparty from the thread's
+own alias — `#{thread.token}@#{thread.relay_domain}` — in both `from` and
+`reply_to`. Decision 1 is why `from` is the alias rather than the
+marketplace's usual address: a `from` that carried the sender's real address
+would mask nothing, whatever `reply_to` said.
### Inbound
`Spree::RelayMailbox` routes on the alias:
-- resolve the thread by token; unknown or closed token is dropped, never
- bounced (a bounce confirms to a guesser which aliases exist)
+- resolve the thread by token *and* the domain the alias was issued for;
+ unknown, expired (`closes_at` in the past) or unmatched is dropped, never
+ bounced — a bounce confirms to a guesser which aliases exist
- identify the sender by the envelope against the thread's two participants;
- a third party is dropped
+ a third party is dropped. The envelope is a claim, not proof: an alias that
+ leaks is repliable by anyone who spoofs the address, which is why the
+ window is short and the alias is per-thread
+- drop a `Message-ID` already stored, so a provider's retry does not deliver
+ the reply twice
- store the message, then mail the counterparty
### API and panel
@@ -123,6 +151,13 @@ the marketplace's own address, as every other Spree email is.
and a seller must be able to ship without it.
- A relay alias is never derived from anything guessable.
+## Retention
+
+Message bodies are personal data about two identified people. The plan is that
+they live as long as the dispute window the operator needs them for, and a
+store preference sets it; a job deletes past it. Deciding that window is the
+operator's, but core must not leave the default as "forever".
+
## Open Questions
- Whether the operator should be able to *post* into a thread or only read it.