Console invite delivery: Keymail federation, then email

Status: design, awaiting review (2026-09-28). Follow-on: email magic-link + passkey sign-in gets its own spec and reuses the console email sender built here (§4).

1. The bug

An account owner invites bill@keymail.dev from the Team page and gets:

> Invited bill@keymail.dev, but delivering the link failed — you can send it > on yourself: https://…/invite/…

Tito's console journal (2026-09-28 14:09 UTC) has the cause:

console: invite send to bill@keymail.dev: keymail: POST /api/app/send: envelope to must be paul@keymail.dev

handleInvite (internal/console/server.go) sends the invite through Keymail.SendApp using the inviter's OAuth grant. Keymail's app API lets a grant deliver to exactly one recipient, the user who approved it (keymail/appapi.go handleAppSend: "The grant authorizes exactly one recipient"). So every invite to anyone but yourself has failed since the invite shipped in 35602776 (2026-08-02), on every deployment. The test fake in keymail_test.go does not enforce that rule, which is why nothing caught it.

A second fault in the same handler: an inviter with no stored grant token sends nothing and still gets the success flash ("the link is in their Keymail Apps inbox").

2. What it should do

Deliver the invite by Keymail if the invitee has a Keymail mailbox, by email if not, and fall back to the hand-off link only when neither works. The flash says which one happened.

Out of scope: the other SendApp callers (sign-in confirmation, CLI sign-in notice, alert watcher). They all send to the grant's own user, which Keymail allows.

3. Keymail delivery by federation

Keymail already has a way for a sender it does not know to reach any mailbox: the federation protocol (keymail/federation.go). It is what one Keymail instance uses to write to another, and it charges an unknown sender a proof of work instead of requiring a grant. The console uses it as a sender in its own name.

3.1 Identity

• From console@<origin host> (e.g. console@console.platform.tito.io), the same From SendApp already pins.
• Signing key: the console's existing long-lived envelope key (Keymail.signKey). Keymail registers a sender by (address, signing key); the same key on every send means the proof of work is paid once per recipient mailbox, and every later send to that mailbox is free.
• Box key: registration also records a key for replies to be sealed to. Nobody replies to an invite and the console serves no Keymail endpoints, so the console generates a P-256 ECDH key per process and never keeps the private half. A later re-registration with a different box key is harmless: Keymail keys free passage on the signing key.

3.2 Flow: Keymail.SendFederated(ctx, to, subject, body) (msgID, error)

All calls go to the configured Keymail base URL (k.base). On keymail.dev that is the relay, which routes every federation verb to the recipient's mailbox by address (keymail/relay.go route).

1. GET /api/federation/lookup?addr=<to>&from=<from> → box_pub, pow_bits. A non-200 here returns ErrNoKeymailMailbox, wrapping Keymail's message. The relay answers 400 "could not determine target mailbox" for an address it cannot resolve and 404 "no such mailbox" for an unknown local part.
2. Seal {subject, body} to box_pub and sign the envelope, exactly as SendApp does today. Factor the shared seal-and-sign into one helper.
3. POST /api/federation/deliver {envelope}. 200 means delivered.
4. On 403 {"error":"unknown_sender","pow_bits":N}: - If N > maxFederationPowBits (24), fail with ErrFederationPriceTooHigh. A mailbox can set its own price, and the console must not burn an HTTP request's worth of CPU on a hostile one. - POST /api/federation/challenge {to, from, sign_pub} → {challenge, bits}. - Mine: find counter with SHA-256(SHA-256(challenge) || sign_pub_raw || counter_be64) having ≥ bits leading zero bits (keymail/internal/pow). A port of pow.Mine of about 30 lines, cancelled by ctx. At 20 bits this is about a million hashes, well under a second. - POST /api/federation/register {to, challenge, counter, from, sign_pub, box_pub, attestation}, where attestation is the signing key's signature over attestationMsg(from, sign_pub, box_pub). - Retry step 3 once.
5. Any other non-200 is an error carrying Keymail's text. A 403 "blocked" is an error like any other: the recipient has blocked the console.

The invite lands in the recipient's main inbox, not Apps. That is the right place for a message from someone who is not an app the recipient granted.

The protocol constants and message shapes (attestationMsg, the pow hash layout, envSigContext) are copied from the Keymail source with a comment naming the file, as keymail.go already does for the envelope.

4. The console email sender

4.1 Where the From address comes from

The identity is created through the platform's own mail layer, the same mail.EnsureDomain walk apps use. It is owned by the built-in ops account bab (internal/release/qualified.go), with the referrer app name console. The send uses the console's own AWS role. No SMTP credential exists, so nothing secret is stored.

Config, read in cmd/console/main.go next to the other CARLOS_MAIL_* variables:

| Variable | Meaning | |---|---| | CARLOS_CONSOLE_MAIL_FROM | Full From address. Optional. |

• Set: use it. Its domain goes through EnsureDomain as whatever DomainKindFor says. A custom domain comes back with pending records that the operator publishes, exactly as for an account's custom domain.
• Unset, CARLOS_MAIL_PLATFORM_SUFFIX set: noreply@console.bab.<suffix>. This is a platform name owned by bab, since platformNameOwnedBy wants the sqid as the label left of the suffix. The DNS writer publishes its records automatically.
• Unset, no suffix, or CARLOS_MAIL_REGION unset (no provisioner): no email fallback. The console logs this once at startup and invites fall back to the hand-off link, as today.

4.2 Lifecycle

• Startup: a background goroutine runs EnsureDomain(bab, "console", domain). It is idempotent: EnsureIdentity reads the identity back rather than minting new DKIM tokens. It logs pending records for a custom domain. A failure is logged and retried on the next send attempt, never fatal, matching how mailBackends degrades.
• Send: ConsoleMailer.Send(ctx, to, subject, body). 1. Check IdentityStatus. Anything but verified returns ErrConsoleMailNotReady. SES would refuse the send anyway; checking first gives a clear log line. Cache a verified result for the process lifetime and anything else for 5 minutes. 2. SESv2 SendEmail with plain-text Simple content, FromEmailAddress = the From address, TenantName = mail.TenantName("bab"), and ConfigurationSetName = the domain record's config set when one exists, so bounces and complaints are counted like any sender's.
• Seam: ConsoleMailer is an interface with one Send method. The SES implementation takes a narrow SESv2 client interface, so tests use a fake.

4.3 Guarding the console referrer

The domain record names console as a referring app in bab. Any teardown path that walks bab's app domains must not delete this domain if an app literally named console is deleted from bab. The plan's first task checks mail.Teardown and the domain-detach paths and either reserves the name console in bab for apps, or records the referrer under a name release.ValidApp accepts but app creation refuses. The plan picks one after reading the code; the spec only requires that no user action on bab can tear down the console's identity.

4.4 IAM (infra/modules/region-host)

New optional variable console_mail_identity_arns (list, default empty). When non-empty, the host role gets:

ses:SendEmail
  Resource: those identity ARNs (+ the config set ARN pattern for the deployment)
  Condition: StringLike ses:FromAddress = the configured From address

The live deployments' existing SES/IAM rights for the provisioner were granted outside this repo (nothing in infra/modules mentions ses:). The plan records where each deployment's grants live before adding to them. Flagship is keymail (271376211898). Tito is titogo (665106592142), and a tofu apply there needs Paul's go. That apply can ride with the store-boundary IAM that already blocks Tito's console upgrade.

5. handleInvite, rewritten

tok := CreateInvite(...)                       // unchanged
link := origin + "/invite/" + tok

ctx 20s
err := km.SendFederated(ctx, to, subj, body)   // Keymail first
if err == nil → flash ok  "…in their Keymail inbox"
log err
if mailer != nil:
    err2 := mailer.Send(ctx, to, subj, body)   // email second
    if err2 == nil → flash ok "…emailed to <to>"
    log err2
flash err "…delivering the link failed… <link>"  // unchanged fallback

• Email is tried after any Keymail failure, not only "no mailbox". The invite link is bound to the invitee's signed-in identity (accepting it requires being signed in as to), so plain email does not weaken it. Delivery matters more here than sealing.
• The inviter's grant is no longer consulted, which also fixes the false success for an inviter with no grant.
• The ValidAddress gate on the invite form stays as it is. Widening who can be invited belongs to the sign-in spec.
• Worst case, the request waits for a Keymail timeout followed by an SES call. The shared 20s context bounds it.

6. Copy (goes through copy review before it is written)

Drafts only. The copy-review skill runs over these before any lands in a file:

1. Flash, Keymail delivered: "Invited {to}. The link is in their Keymail inbox."
2. Flash, emailed: "Invited {to}. We emailed them the link."
3. Flash, both failed: unchanged ("Invited {to}, but delivering the link failed — you can send it on yourself: {link}"). It has an em dash, so review it too.
4. Message subject: unchanged ("You've been invited to an account on the CARLOS platform").
5. Message body: unchanged text, reviewed as one string because email now carries it.

7. Testing

• Keymail fake (keymail_test.go): /api/app/send enforces to == grant user and answers 403 with Keymail's message otherwise. This is the regression test for §1. It also gains lookup (resolvable and unresolvable addresses), challenge, register and deliver, with a real pow check at 8 bits, a sender registry keyed by (from, sign_pub), and a configurable price.
• SendFederated: - a known sender delivers without pow; - an unknown sender mines, registers and delivers; - a price above the cap is refused without mining; - a blocked sender gets an error; - an unresolvable address gets ErrNoKeymailMailbox; - the delivered envelope verifies and unseals.
• ConsoleMailer with a fake SESv2 client: - unverified → ErrConsoleMailNotReady and no send; - verified → one SendEmail with tenant, config set and From set; - the verified cache holds.
• handleInvite, table-driven over: - Keymail ok; - no mailbox + email ok; - Keymail error + email ok; - both fail; - no mailer + Keymail fails; - inviter with no grant still delivers.

Each case asserts the flash kind and text, and that the invite row exists either way.

• Config: the From resolution table in §4.1.
• GOOS=darwin and GOOS=windows builds stay green (cross-compile gate).

8. Rollout

1. Merge, then roll consoles by the normal recipe. Keymail federation works immediately with no infra change, so the §1 bug is fixed as soon as a console runs the build.
2. Flagship: apply the region-host variable, restart the console, check the identity verifies, and invite a non-Keymail address.
3. Tito: blocked on the store-boundary IAM (Tito's console is pinned on cf02a4d5). Bundle the SES grant with that apply, with Paul's go.