carlos / platform Public

email events push: tell the app itself, signed, at a path on its own host

`carlos email events` let a member see what happened to a message. This
tells the app. An app that asks — `carlos email events push --app <a>
--path /mail/events` — is POSTed each Delivery, Bounce, Complaint, Reject
and DeliveryDelay SES reports for a message it sent, as JSON, signed.

What crosses, and to whom. The payload names the recipient, and a
recipient's address is the sending app's business. Only a notification SES
attributed to the app's own sending identity (senderAmong, a by_sender row)
is ever queued for it; an event attributable only by a domain several apps
share stays in the log and is never pushed. A Send is not pushed: the app
had that from SES in the reply to its own send.

Where it goes. Only https://<app>.<account>.<AppsDomain><path>. The host is
built from platform-validated names, never from a request, and the path
passes schedule.ValidPath. Redirects are refused, so a far end cannot turn
a delivery into a POST of somebody's address at a host it chooses. It
travels the public edge, which is what wakes a hibernating app — and why a
gated app cannot receive one; the CLI says so when it sees a 401.

How an app knows it is real. The console signs with an Ed25519 key kept for
this alone (MailEventsSigningKey, beside and separate from the keymail
envelope key, in the same keys table). Turning the push on delivers the
public half to the app as CARLOS_MAIL_EVENTS_KEY — before the hook is
recorded, so events never flow to an app with nothing to check them with.
The header is `Carlos-Signature: t=<unix>,ed25519=<b64>` over
"carlos-mail-event\n" + t + "\n" + body. VerifyMailEvent is the scheme's one
executable definition and the tests hold both ends to it. The key is the
deployment's, so an app must also check the body's account and app are its
own; the docs say so.

Delivery. A queue in the console DB, one row per notification per app,
UNIQUE on the SNS notice so a redelivery queues once, carrying the same id
on every retry. A pass every 15s sends what is due, 20s per POST, a batch
of 50 and a minute's budget, retrying non-2xx at 1m, 5m, 15m, 1h, 3h, 6h
and 12h before giving up. The payload is a copy of the log's addresses, so
queued rows are dropped at the same 30 days, delivered or not. Turning the
push off gives up on what is still queued and unsets the key.

Doors: GET/PUT/DELETE /api/cli/apps/{account}/{app}/email/events/push,
Admin, 404 with no email provisioner and for non-members like the rest of
the family, 503 on a deployment with no apps domain rather than recording a
push that could never arrive. The CLI shows where events go, the key
variable, delivered/waiting/given-up counts, and the last failure in the far
end's terms — "answered 404" pointing at a missing handler, "answered 401"
at a gate.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>