Durable system-email intent and classified delivery outcomes

[vidarbrekke]

Problem

Published EmDash/Auth 1.2.0 does not provide a durable email contract for system messages and application-owned transactional notifications.

The current API has these properties:

• EmailDeliverEvent contains the message and source, and the delivery handler returns Promise<void>.
• Auth creates a magic-link token before calling its configured email callback.
• System messages bypass the ordinary plugin before/after middleware.
• A provider or transport plugin cannot recover an email obligation that was not durably persisted when Auth committed the token.
• A transport that returns successfully after queueing can cause an application caller to mark a notification sent and purge its payload before provider acceptance.

The API cannot distinguish provider acceptance from pending queue work, permanent rejection, or an unknown result. It also does not expose a stable send identity, exact expiry, durable retry state, or restart recovery.

Use case

A site uses magic-link login, invitations, account recovery, and application-owned transactional notifications through an EmDash email provider. The provider may reject a message, accept it while the response is lost, or report only that it queued the message.

The site needs to preserve the delivery obligation and make the result recoverable without resending an expired credential or marking queued work as accepted. Auth flows, application workflows, operators, and recipients are affected.

The contract must cover both system and application messages while preserving system-email hook isolation.

Current workarounds

Operators can install a provider plugin and use the admin test-email flow. A transport plugin can persist messages that reach email:deliver, and an application can maintain its own notification outbox or provider integration.

These workarounds cannot atomically preserve an Auth delivery obligation that fails before the transport receives it. They also cannot make Promise<void> distinguish accepted, pending, rejected, and unknown outcomes. A plugin can provide transport persistence, but it cannot provide the required system-email guarantee without a host-owned durable intent and outcome contract.

Your involvement

• I am requesting this capability.
• I am offering to champion the design in a feature plan or RFC.
• I am offering to implement it after the design is accepted.

[github-actions[bot]]

Design PR #4209 proposes proposals/durable-system-email-delivery.md for this Idea. Review of the design continues on the pull request.

[vidarbrekke]

Update: I am volunteering to champion this RFC

Draft design PR: #4209

This proposal is intentionally RFC-level because it crosses Auth, the public
email provider contract, durable stored state, retry/recovery, and security
boundaries.

I have prepared a draft design proposal limited to proposals/. Its intended
scope is:

• a host-owned durable email intent;
• classified outcomes for accepted, pending, rejected, and unknown;
• stable delivery identity and idempotent retry;
• atomic preservation of Auth credentials and their system-email obligation;
• expiry-safe recovery and restart behavior; and
• preservation of system-email hook isolation.

I am ready to implement the accepted design. Would a Maintainer sponsor this
RFC, or should I narrow the first version to system-auth emails before opening
the design PR?

The proposal deliberately leaves provider-specific acceptance semantics,
legacy Promise<void> compatibility, payload retention, and the boundary for
application-owned notifications as explicit review questions rather than
assuming those decisions.

[vidarbrekke]

Correction — tested version and current status (2026-10-19)

The reproduction baseline for the statements above was EmDash/Auth 1.2.0. The latest published versions of emdash, @emdash-cms/auth, and @emdash-cms/cloudflare are 1.3.1 (EmDash on npm, Auth on npm, Cloudflare on npm). I have not rerun the failure sequence on 1.3.1, so the 1.2.0 ordering and failure observations above are historical reproduction evidence, not a claim that each was independently reproduced on 1.3.1.

The delivery-contract gap remains: the current hook type still models delivery as Promise<void> (core hook types, Cloudflare adapter). The Auth 1.3.1 changelog records no changes (Auth changelog). RFC PR #4209 remains a draft and is not a shipped implementation. Please treat the 1.2.0 behavior as the reported baseline and the durable contract as an unresolved design request, not as a verified 1.3.1 reproduction.