# Tenant Email, Plan 5 of 5: Instance senders > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Give one instance of an app its own From address, its own IAM user, its own SES tenant, its own cap, its own pause and its own counts, with the credential delivered through plan 4's per-instance config layer and never through the bundle every sibling reads. An app enters **per-instance mode** on its first instance enable — one CAS write on `senders/app.json` that sets `PerInstance`, deactivates the app sender and stamps `PauseKindPerInstance`, followed by a list-and-delete reap of every key the app sender and its standalones hold, followed by unsetting the app sender's `CARLOS_SMTP_*` from the default bundle — and leaves it when the last instance sender is torn down. Seven doors under `/api/cli/apps/{account}/{app}/instances/{host}/email` carry `svcrole.Mail`; `enable` refuses twice, with a sentence each: once when the instance's process would share a uid with a sibling, and once when the box it runs on is not running an agent that renders the instance layer. **Architecture:** `internal/mail` gains `instance.go`: `DeclareInstance`, `EnterPerInstance`, `LeavePerInstance`, `EnableInstance`, `RotateInstance`, `TeardownInstance`, and the delivery helpers that write through `appconfig.ApplyInstance` instead of `appconfig.Apply`. The app-level walks are widened rather than duplicated: `grantedDomains` and `RefreshPolicies` stop walking `DomainRecord.Apps` and walk a new `Senders []string` of `"/"` references, with a legacy record's `Apps` read as one app-sender reference each, so an instance sender's policy is refreshed when its configuration set is rebound — the 554 that #271 and #279 already cost this codebase, reached through a new door. `claimDomain` carries the sender and refuses a re-claim by a different `(app, sender)`, including inside one account. `EnsureDomain` and `Teardown` keep their signatures and delegate to new `…ForSender` forms with `SenderAppID`, so every existing caller and test compiles unchanged. Console-side, `internal/console/apimailinstance.go` holds the family: one gate on `apiinstancemove.go`'s `moveGate` shape, the two enable refusals, and the seven handlers. Both refusals read the box record, because a box is the only thing that knows either answer and a console reads only its own registry: task 7 adds `ConfigSchema` (which config-layer schema this agent renders) and `RouteUIDs` (host -> the uid shape this box renders for that route) to `status.Probes` and `status.BoxMetrics`, stamped on the status tick that already stamps `Release` and `RouteVersions`. **Tech Stack:** Go 1.26, `internal/mail` (senders, walks, domains, claims), `internal/appconfig` (plan 4's instance layer and `ConfigAck`), `internal/provision` (`InstanceID`, `GetRecord`, `ValidHostShape`), `internal/registry` (route rows), `internal/caps` (the host_role render rule), `internal/status` (the box record), `internal/host` (the agent's status tick), `internal/console` (the email and instance door families), `internal/svcrole`, root-package `mail_cli.go`. **Spec:** `docs/superpowers/specs/2026-09-15-tenant-email-senders-design.md` — §11 step 5 is the whole mandate: §6.3 (entering and leaving per-instance mode), §6.4 (the doors, the uid check, the domain attach), and the parts of §8 that key caps, pauses, counts and status to an instance sender. §5 landed in plan 2, §7 in plan 3, §6.2 and §6.5 in plan 4. §10 (the relay), §12's `slices.Compact` policy-size work and §13 are out of scope. §11 step 6 (per-instance machine tokens) is explicitly **not** this plan: the instance doors are `Allow(svcrole.Mail)` and the caller is titogo's hub, not the customer's own code. **Four rulings, taken before the tasks and not to be reopened during them.** 1. **`claimDomain` refuses a same-account re-claim by a different `(app, sender)`, and that ends cross-app domain sharing inside one account.** Today `claimDomain` returns success for any re-claim by the holder's own account (`domainclaim.go`, the `cur.Account != acct` branch), and `EnsureDomain` then appends the second app to `rec.Apps` — so two apps in one account can legitimately send from one domain, and some do. §6.4 requires the refusal anyway, because without it one instance sender attaches a sibling instance's already-verified domain and inherits its identity with no proof of its own, which is the cross-account hole §4a closed reappearing one level down. The refusal is therefore literal: a claim held by `(app A, sender app)` refuses `(app B, sender app)` with `ErrDomainHeldBySender`. **This is a behaviour change with a member-visible consequence and it belongs in the roll note** (task 13): an account that wants two apps on one domain needs a second domain, or a per-domain grant this design does not build. Every domain already claimed keeps working — the refusal only ever fires on a *new* attach. 2. **Both enable refusals read the box record, and the box record gains the two fields that make them answerable.** §6.5 says the delivery check "reads the box record's agent version, so its refusal names the box and the version rather than guessing" from an absent ack. The box record has two version-shaped fields and neither answers the question: `BoxMetrics.Release` is `version.Build`, a git short sha (`internal/version/version.go`, `Makefile`'s `LDFLAGS`), so no comparison is definable over it; `BoxMetrics.System.Version` is the semver of the last *self-update*, absent entirely on a box rolled by hand with `update-platform-binary.sh`. The uid check has a worse problem: the facts it needs — `registry.Route.Backing` and the operator's `caps` grant column — live in a box's own SQLite registry, and a console reads only the registry of the box it runs on (`internal/console/view.go`'s `openRegistry`, `apiroutes.go`'s 503 when `s.cfg.Registry == ""`), so a console cannot answer it for an instance on any other box. Both are therefore answered the only honest way: **the box says**. Task 7 adds `Probes.ConfigSchema`/`BoxMetrics.ConfigSchema` (stamped from `appconfig.ConfigAckSchema`) and `Probes.RouteUIDs`/`BoxMetrics.RouteUIDs` (host -> `"dynamic"`, `"app"` or `"agent"`), both on the status tick that already stamps `Release` and `RouteVersions`, both bucket-private in `Metrics` exactly as `RouteVersions` is and for the same reason (it is hostname-keyed and `BuildFleet` never copies `Metrics` into the public feed). Both are present on every box within one heartbeat of a roll, both let the refusal name the box, and `status.BoxStale` decides a silent box. **Acks stay change-only, and absence means "not yet delivered".** §6.5 records why the every-pass ack was refused: it is a Get and a Put per converged route per pass on every box, and on a fleet-door box every one of those writes would fail, because `control/config-ack/` is outside the door's read and write scopes (`internal/edge/storedoor.go:389`, `:489`). So plan 4 gives this plan `ConfigAck.Schema` and `ConfigAck.InstanceConfigETag` written when a delivery changes, `LatestConfigAck`, and `InstanceConfigDelivery` returning `InstanceConfigDelivered`, `InstanceConfigStale`, `InstanceConfigNotYetDelivered` or `InstanceConfigUnknownAgent`. Delivery is still decidable where it matters, because writing an instance's credential always changes that instance's file and so always produces an ack. A missing ack is never read as "old agent" — the box record answers that — and **an instance on a fleet-door box can be enabled but its delivery reads as unconfirmed forever**, which task 13 puts in the roll note and which the door grant is its own piece of work. 3. **`EnsureDomain`, `Teardown`, `RefreshPolicies` and `grantedDomains` are widened by delegation, not by changing every caller.** `EnsureDomain(ctx, s, p, w, d, acct, app, domain, now)` and `Teardown(ctx, s, p, w, d, acct, app)` keep their exact signatures and become one-line wrappers over `EnsureDomainForSender` / `TeardownSender` with `SenderAppID`. `grantedDomains` and `RefreshPolicies` do change shape, because every one of their callers is inside `internal/mail` and the console, and a sender-blind version of either is the #271 failure waiting to happen. 4. **The uid check has exactly ONE passing shape today, because the isolated-exec layout does not give a per-instance uid.** §6.4 names two: `DynamicUser=yes` with no host_role grant, or "an exec route under an isolated-exec layout with a per-instance uid". The second does not exist in this tree. `internal/host/units/carlos-instance@.service` sets `User=carlos`/`Group=carlos`, as do the seed and sidecar templates; the isolated-exec design says so deliberately under "Why nested and not per-instance uids" (`docs/superpowers/specs/2026-09-11-isolated-exec-design.md`), which records that per-instance uids need a uid allocator and a root chown per migration and leaves it as later hardening, and §12 of the same document records that the agent cannot do it without `CAP_SETUID`. Nesting buys a mount namespace, which hides a sibling's *files* but not a sibling's *uid*: every nested instance shares uid `carlos` with every other nested instance and with the agent. So the uid verdict this plan builds has three values and only `"dynamic"` passes. **Do not add a nested-layout branch to make the second shape pass** — it would assert a property the units do not have, and `internal/edge/purge.go` already documents the exact gap. File the per-instance-uid follow-up as an amadan discussion on `carlos/platform`, never a GitHub issue. ## Global Constraints - **Run `gofmt -w` on every file you touched before running the gate.** `gofmt -l .` only NAMES an unformatted file; it fixes nothing. Several blocks below are pasted with aligned trailing comments (task 1's `Sender` field writes, task 2's `SenderRefs` table test, task 7's `BoxMetrics` field) that gofmt will realign, so a plan followed literally goes red on the gate's last step unless `gofmt -w` ran first. - **The gate before every commit:** `go build ./... && go vet ./... && go test ./... -count=1` all clean, and `gofmt -l .` empty over the whole tree. Env: `GOCACHE=/tmp/claude-1001/gocache GOFLAGS=-mod=mod GOPROXY=off`. Go may need `GOCACHE` pointed somewhere writable — "read-only file system" from the toolchain is that tell, and the Bash sandbox may need disabling for the Go commands alone. - **Socket-binding tests need `TMPDIR=/tmp/g`.** `internal/host` and `internal/console` both have tests that bind unix sockets, and the default sandbox `TMPDIR` produces a path past `sockaddr_un`'s 107 bytes. Task 7 touches `internal/host`, so run that package's tests as `TMPDIR=/tmp/g go test ./internal/host/ -count=1`. - **This repo lands through `amadan branch merge`, never a GitHub PR.** Branch `worktree-tenant-email-senders`. CI is `.amadan/ci.d/`, triggered by a push to the `amadan` remote; a branch pushed only to `origin` has been gated by nothing. Do not run `gh pr create` and do not file a GitHub issue — follow-ups are amadan discussions on `carlos/platform`. - **Every line number in this plan is PRE-plans-2-through-4.** Plans 2, 3 and 4 land before this one and move every file this plan touches. Treat every `file.go:NNN` below as provenance for where a thing was when this plan was written, and **navigate by function name**, never by line. Where a plan-2/3/4 name is consumed, it is named in full in the task's Consumes block. - **Cross-compile gate.** CI builds darwin and windows as well as linux. Nothing in this plan should reach for a linux-only syscall, but if a task ends up in `internal/host` needing one, it needs a `//go:build linux` file and a `!linux` stub beside it. - **No new capability for anyone who does not ask for it.** Every task must leave the tree shippable on its own: an app sending today sends after each commit, with the same credential, the same cap, the same delivered variables and the same doors. The deliberate behaviour changes are ruling 1's claim refusal (task 3) and the app sender's credential being reaped on entry to per-instance mode (task 4) — both are roll notes, and both are reachable only by an account that asks for an instance sender. - **Wire-shape changes are additive.** Live `DomainRecord`, `DomainClaim`, `Sender` and `Box` objects exist in production buckets and must still parse after every task. `Senders`, `Sender` (on the claim) and `ConfigSchema` are all `omitempty`, and a record that carries none of them reads exactly as it reads today. - **Copy:** no em dashes. Full stop and a new sentence, lower case. Comments are full sentences saying why, never process history; log lines use `->` between values. - **Tasks 9, 10, 11 and 12 add member-facing strings** (door refusals, CLI status lines). Run the `copy-review` skill on the new strings BEFORE they land in a file, and apply the user's edits verbatim. Count each string's occurrences at the base commit first: a refusal reused by two doors is one review, not two. - Commit after every task with the trailer `Co-Authored-By: Claude Opus 5 `. --- ## File Structure | File | Responsibility | |---|---| | `internal/mail/instance.go` (create) | `InstanceSenderID`, `DeclareInstance`, `EnterPerInstance`, `LeavePerInstance`, `EnableInstance`, `RotateInstance`, `TeardownInstance`, `EnvDeliveredInstance`, `writeSMTPEnvInstance` | | `internal/mail/instance_test.go` (create) | the instance sender's record and names, the transition's one CAS, the reap-not-deactivate rule, the enable race, delivery into the layer only | | `internal/mail/domain.go` (modify) | `DomainRecord.Senders`, `SenderRef`, `SenderRefs`, `AddSenderRef`, `RemoveSenderRef` | | `internal/mail/domainclaim.go` (modify) | `DomainClaim.Sender`; `claimDomain` takes a sender and refuses a different `(app, sender)`; `ErrDomainHeldBySender` | | `internal/mail/walk.go` (modify) | `grantedDomains` and `RefreshPolicies` walk sender refs; `EnsureDomainForSender`; `TeardownSender`; `Enable` refuses under `PerInstance` | | `internal/status/snapshot.go` (modify) | `Probes.ConfigSchema`/`RouteUIDs`, `BoxMetrics.ConfigSchema`/`RouteUIDs`, both carried through `CollectBox` | | `internal/host/agent.go` (modify) | the status tick stamps `ConfigSchema` from `appconfig.ConfigAckSchema` and `RouteUIDs` from `routeUIDShape` | | `internal/host/metrics_loop.go` (modify) | `routeUIDShape(rt registry.Route) string`, the one place the uid verdict is computed | | `internal/console/apimailinstance.go` (create) | `emailInstanceGate`, `instanceBoxFacts`, `instanceOwnUID`, `instanceLayerAgent`, the seven handlers, `registerEmailInstanceRoutes` | | `internal/console/apimailinstance_test.go` (create) | the two refusals, the door list, a stranger's 404, the transition through the door | | `internal/console/apimail.go` (modify) | `mailAppDomains` walks sender refs; `emailReply`'s `senders` array carries instance senders; the status door resumes every sender; the pause door's `instance` field | | `internal/console/svcroutes_test.go` (modify) | the seven doors join `TestMailRoleReachesExactlyTheEmailDoors`'s `want` | | `mail_cli.go` (modify) | `apiEmailSender` gains its instance fields; `carlos email status --instance`; a line per instance sender | | `README.md` (modify) | the roll note: the claim refusal, the app credential reap, the ConfigSchema heartbeat | --- ### Task 1: The instance sender's record **Files:** - Create: `internal/mail/instance.go`, `internal/mail/instance_test.go` **Interfaces:** - Consumes: plan 2's `Sender`, `ScopeInstance`, `SourceDomain`, `SenderAppID`, `ValidSenderID`, `SenderKey`, `GetSender`, `PutSender`, `ListSenders`, `SenderNames`, `SenderNameSet` (`internal/mail/sender.go`); `Declared` (`mail.go`), `ValidEnvPrefix`/`DefaultEnvPrefix` (`envnames.go`), `appconfig.ValidVarValue` (`internal/appconfig/materialize.go:23`), `release.ValidAccount`/`ValidApp`. - Produces: ```go func InstanceSenderID(host string) string // == provision.InstanceID(host), spelled here so internal/mail never imports internal/provision func DeclareInstance(ctx context.Context, s release.Store, acct, app, senderID, host, envPrefix, from, actor string, now time.Time) (*Sender, error) func InstanceSenders(ctx context.Context, s release.Store, acct, app string) ([]*Sender, error) var ErrNotInstanceSender = errors.New("mail: that sender is not an instance sender") var ErrInstanceHostMoved = errors.New("mail: an instance sender's host cannot change") ``` - [ ] **Step 1: Write the failing test** `internal/mail/instance_test.go` (create): ```go package mail import ( "context" "errors" "testing" "time" "github.com/carlosframework/platform/internal/release" ) // An instance sender is declared the way an app sender is, and carries the // three things an app sender never has: a scope, a host and a slug. The slug // is computed once, here, because nothing can parse a hash back and the // caller index (plan 2) is keyed on the name the slug produces. func TestDeclareInstanceWritesItsOwnSenderWithASlug(t *testing.T) { ctx := context.Background() s := release.NewDirStore(t.TempDir()) now := time.Date(2026, 9, 15, 12, 0, 0, 0, time.UTC) const host = "book.example.com" sn, err := DeclareInstance(ctx, s, "bag", "harbourmail", InstanceSenderID(host), host, "HARBOURMAIL_SMTP", "hello@book.example.com", "owner@example.test", now) if err != nil { t.Fatal(err) } if sn.Scope != ScopeInstance || sn.Source != SourceDomain || sn.Host != host { t.Fatalf("declared sender is not an instance sender: %+v", sn) } if sn.ID != host { t.Fatalf("sender id = %q, want the instance id of %q", sn.ID, host) } if sn.Slug == "" { t.Fatal("an instance sender was declared with no slug, so nothing can name its IAM user") } // It lives under its own key, so two instances declaring at once never // contend on one etag. back, _, err := GetSender(ctx, s, "bag", "harbourmail", sn.ID) if err != nil { t.Fatal(err) } if back == nil || back.Slug != sn.Slug || back.Declared.From != "hello@book.example.com" { t.Fatalf("round trip lost the sender: %+v", back) } // The app sender is untouched by an instance declaration. app, _, err := GetSender(ctx, s, "bag", "harbourmail", SenderAppID) if err != nil { t.Fatal(err) } if app != nil { t.Fatalf("declaring an instance sender wrote the app sender: %+v", app) } } // The slug is stable across a re-declare, because it is the IAM user name // and the tenant name. Recomputing it on every declare would strand a // principal under the old name on every From change. func TestDeclareInstanceKeepsTheSlugAndRefusesAHostMove(t *testing.T) { ctx := context.Background() s := release.NewDirStore(t.TempDir()) now := time.Date(2026, 9, 15, 12, 0, 0, 0, time.UTC) const host = "book.example.com" id := InstanceSenderID(host) first, err := DeclareInstance(ctx, s, "bag", "harbourmail", id, host, "HARBOURMAIL_SMTP", "hello@book.example.com", "owner@example.test", now) if err != nil { t.Fatal(err) } second, err := DeclareInstance(ctx, s, "bag", "harbourmail", id, host, "HARBOURMAIL_SMTP", "sales@book.example.com", "owner@example.test", now) if err != nil { t.Fatal(err) } if second.Slug != first.Slug { t.Fatalf("re-declare moved the slug %q -> %q, stranding the IAM user", first.Slug, second.Slug) } if _, err := DeclareInstance(ctx, s, "bag", "harbourmail", id, "other.example.com", "HARBOURMAIL_SMTP", "hello@other.example.com", "owner@example.test", now); !errors.Is(err, ErrInstanceHostMoved) { t.Fatalf("re-declare under a different host = %v, want ErrInstanceHostMoved", err) } } // InstanceSenders is every instance sender of an app and never the app // sender, which is what the status reply and the teardown door both walk. func TestInstanceSendersExcludesTheAppSender(t *testing.T) { ctx := context.Background() s := release.NewDirStore(t.TempDir()) now := time.Date(2026, 9, 15, 12, 0, 0, 0, time.UTC) if _, err := PutSender(ctx, s, "bag", "harbourmail", &Sender{ ID: SenderAppID, Scope: ScopeApp, Source: SourceDomain, Declared: &Declared{EnvPrefix: "HARBOURMAIL_SMTP", From: "x@y.com", At: now, By: "o"}, }, ""); err != nil { t.Fatal(err) } for _, host := range []string{"book.example.com", "shop.example.com"} { if _, err := DeclareInstance(ctx, s, "bag", "harbourmail", InstanceSenderID(host), host, "HARBOURMAIL_SMTP", "hello@"+host, "owner@example.test", now); err != nil { t.Fatal(err) } } got, err := InstanceSenders(ctx, s, "bag", "harbourmail") if err != nil { t.Fatal(err) } if len(got) != 2 || got[0].ID != "book.example.com" || got[1].ID != "shop.example.com" { t.Fatalf("InstanceSenders = %+v, want the two instance senders sorted by id", got) } } ``` - [ ] **Step 2: Run the test — expect failure** ```bash GOCACHE=/tmp/claude-1001/gocache GOFLAGS=-mod=mod GOPROXY=off go test ./internal/mail/ -run TestDeclareInstance -count=1 ``` Expected: build failure, `undefined: InstanceSenderID`, `undefined: DeclareInstance`, `undefined: InstanceSenders`, `undefined: ErrInstanceHostMoved`. - [ ] **Step 3: Implement** `internal/mail/instance.go` (create): ```go // Instance senders (design §6.3, §6.4): one instance of an app with its own // From address, its own IAM principal, its own tenant, its own cap and its // own counts, delivered through the per-instance config layer and never // through the bundle every sibling of that instance reads. package mail import ( "context" "crypto/sha256" "encoding/hex" "errors" "fmt" "sort" "strings" "time" "github.com/carlosframework/platform/internal/appconfig" "github.com/carlosframework/platform/internal/release" ) var ( // ErrNotInstanceSender is an instance verb aimed at the app sender, or // at a sender some other scope owns. The verbs in this file edit one // instance's estate and must never reach the app's. ErrNotInstanceSender = errors.New("mail: that sender is not an instance sender") // ErrInstanceHostMoved is a re-declare naming a different host for an // id that already exists. The id is derived from the host, so this can // only mean a hash collision between two long hosts, and treating it as // the same sender would deliver one instance's credential to another. ErrInstanceHostMoved = errors.New("mail: an instance sender's host cannot change") ) // maxInstanceID mirrors provision.MaxInstanceID. InstanceSenderID is spelled // here rather than delegating so internal/mail keeps its three imports: // internal/provision pulls in internal/registry and internal/controlname, // and a mail package that imported the provisioning layer would be a // dependency edge in the wrong direction (the console composes the two, and // nothing in internal/mail knows what an instance record is). // // The two implementations are pinned against each other by a test in // internal/console, where both packages are already in scope. const maxInstanceID = 40 // InstanceSenderID is the sender id for a host: the host itself when it is // short enough to be its own identifier, and the same bounded hash form // provision.InstanceID produces otherwise. The underscore prefix is what // keeps the two forms in one namespace: no valid host contains one. func InstanceSenderID(host string) string { if len(host) <= maxInstanceID { return host } sum := sha256.Sum256([]byte(host)) return "_" + host[:22] + "-" + hex.EncodeToString(sum[:8]) } // DeclareInstance records one instance's half: the env prefix it wants its // variables under and the From address it sends as. It is Declare's // counterpart, and it refuses the same things Declare refuses, for the same // reasons: the prefix is locked once delivery has happened, and the From // address is validated before anything is spent because it is delivered // verbatim and an unrenderable byte caught later would strand a key. // // The SLUG is computed once, here, and never again. It is the second half of // this sender's IAM user name and the whole of its tenant name, so // recomputing it on a later declare would leave a live principal under a // name no record points at. Plan 2's ResolveSenderNames owns the collision // case, at enable, where the caller index it writes can see one. func DeclareInstance(ctx context.Context, s release.Store, acct, app, senderID, host, envPrefix, from, actor string, now time.Time) (*Sender, error) { if !release.ValidAccount(acct) { return nil, fmt.Errorf("mail: invalid account %q", acct) } if !release.ValidApp(app) { return nil, fmt.Errorf("mail: invalid app %q", app) } if !ValidSenderID(senderID) || senderID == SenderAppID { return nil, fmt.Errorf("mail: invalid instance sender id %q", senderID) } if host == "" || InstanceSenderID(host) != senderID { return nil, fmt.Errorf("mail: sender id %q does not name host %q", senderID, host) } if envPrefix == "" { envPrefix = DefaultEnvPrefix } if !ValidEnvPrefix(envPrefix) { return nil, fmt.Errorf("mail: invalid env prefix %q — want ^[A-Z][A-Z0-9_]{0,31}$", envPrefix) } if !strings.Contains(from, "@") { return nil, fmt.Errorf("mail: From %q is not an address", from) } if err := appconfig.ValidVarValue(from); err != nil { return nil, fmt.Errorf("mail: From %q is not EnvironmentFile-safe: %w", from, err) } sn, etag, err := GetSender(ctx, s, acct, app, senderID) if err != nil { return nil, err } if sn == nil { names, err := SenderNames(acct, app, senderID, "") if err != nil { return nil, err } sn = &Sender{ID: senderID, Slug: names.Slug, Scope: ScopeInstance, Source: SourceDomain, Host: host} } if sn.Scope != ScopeInstance { return nil, ErrNotInstanceSender } if sn.Host != host { return nil, fmt.Errorf("mail: sender %q is host %q: %w", senderID, sn.Host, ErrInstanceHostMoved) } if sn.Declared != nil && sn.Provisioned != nil && sn.Declared.EnvPrefix != envPrefix { return nil, fmt.Errorf("mail: env prefix is %q and cannot move after delivery", sn.Declared.EnvPrefix) } sn.Declared = &Declared{EnvPrefix: envPrefix, From: from, At: now, By: actor} if _, err := PutSender(ctx, s, acct, app, sn, etag); err != nil { return nil, err } return sn, nil } // InstanceSenders is every instance sender an app has, sorted by id, and // never the app sender. The teardown door walks it to decide whether the // one it just removed was the last, and the status reply walks it to print // a line each. func InstanceSenders(ctx context.Context, s release.Store, acct, app string) ([]*Sender, error) { all, err := ListSenders(ctx, s, acct, app) if err != nil { return nil, err } var out []*Sender for _, sn := range all { if sn != nil && sn.Scope == ScopeInstance { out = append(out, sn) } } sort.Slice(out, func(i, j int) bool { return out[i].ID < out[j].ID }) return out, nil } ``` - [ ] **Step 4: Run the test — expect success** ```bash GOCACHE=/tmp/claude-1001/gocache GOFLAGS=-mod=mod GOPROXY=off go test ./internal/mail/ -count=1 ``` - [ ] **Step 5: Gate and commit** ```bash gofmt -w internal/mail/instance.go internal/mail/instance_test.go GOCACHE=/tmp/claude-1001/gocache GOFLAGS=-mod=mod GOPROXY=off go build ./... && \ GOCACHE=/tmp/claude-1001/gocache GOFLAGS=-mod=mod GOPROXY=off go vet ./... && \ GOCACHE=/tmp/claude-1001/gocache GOFLAGS=-mod=mod GOPROXY=off go test ./... -count=1 && \ gofmt -l . git add internal/mail/instance.go internal/mail/instance_test.go git commit -m "mail: declare an instance sender, with its own slug and key (plan 5, task 1) Co-Authored-By: Claude Opus 5 " ``` --- ### Task 2: A domain record names senders, and the two policy walks follow them **Files:** - Modify: `internal/mail/domain.go` (`DomainRecord` struct, `AddApp`, `RemoveApp`), `internal/mail/walk.go` (`grantedDomains`, `RefreshPolicies`, and their callers in `EnsureDomain`, `VerifyDomain`, `Enable`, `CreateStandalone`), `internal/mail/instance.go` (`senderNamesOf`), `internal/console/apimail.go` (`mailAppDomains`), `internal/mail/domain_test.go`, `internal/mail/walk_lifecycle_test.go` **Interfaces:** - Consumes: plan 2's `SenderNames`, `SenderNameSet`, `GetSender`, `Sender.Salt`, `SenderAppID`; `UserName`/`StandaloneUserName`/`UserPath` (`policy.go`), `VerifiedARNs`/`VerifiedConfigSetARNs` (`domain.go:144`, `:164`), `Provisioner.EnsureUser`. - Produces: ```go // internal/mail/domain.go // DomainRecord gains: Senders []string `json:"senders,omitempty"` func SenderRef(app, sender string) string // "/" func SplitSenderRef(ref string) (app, sender string, ok bool) func (r *DomainRecord) SenderRefs() []string // Senders, plus one app-sender ref per legacy Apps entry func (r *DomainRecord) HasSender(app, sender string) bool func (r *DomainRecord) AddSenderRef(app, sender string) bool func (r *DomainRecord) RemoveSenderRef(app, sender string) bool // internal/mail/walk.go func grantedDomains(ctx context.Context, s release.Store, acct, app, sender string) ([]*DomainRecord, error) // unexported, gains sender func RefreshPolicies(ctx context.Context, s release.Store, p Provisioner, acct string, refs []string) error // was apps []string // internal/mail/instance.go func senderNamesOf(acct, app string, sn *Sender) (SenderNameSet, error) // unexported // internal/console/apimail.go func (s *Server) mailAppDomains(ctx context.Context, acct *Account, app string) ([]*mail.DomainRecord, error) // now filters on the APP sender's ref ``` - [ ] **Step 1: Write the failing test** `internal/mail/domain_test.go` (append; create in package `mail` if it does not exist): ```go // A record written before senders existed carries Apps and no Senders, and // must read as one app-sender reference per app. Without that, the first // RefreshPolicies after this release would find no principals for every // domain in the fleet and silently refresh nothing. func TestSenderRefsReadsALegacyRecordsAppsAsAppSenders(t *testing.T) { rec := &DomainRecord{Domain: "x.com", Apps: []string{"harbourmail", "keymail"}} want := []string{"harbourmail/app", "keymail/app"} if got := rec.SenderRefs(); !reflect.DeepEqual(got, want) { t.Fatalf("SenderRefs() = %q, want %q", got, want) } if !rec.HasSender("harbourmail", SenderAppID) || rec.HasSender("harbourmail", "book.example.com") { t.Fatal("a legacy record answered HasSender for something other than its app senders") } } // An instance sender joins Senders and NEVER joins Apps. Apps is what the // app sender's own policy is computed from (grantedDomains), so a customer // domain reaching it would put that customer's identity in the app-wide // credential every sibling instance holds. func TestAddSenderRefForAnInstanceNeverJoinsApps(t *testing.T) { rec := &DomainRecord{Domain: "book.example.com"} if !rec.AddSenderRef("harbourmail", "book.example.com") { t.Fatal("AddSenderRef reported no change on a fresh record") } if len(rec.Apps) != 0 { t.Fatalf("an instance sender's attach added to Apps: %q", rec.Apps) } if !rec.HasSender("harbourmail", "book.example.com") || rec.HasSender("harbourmail", SenderAppID) { t.Fatalf("HasSender is wrong after the attach: %+v", rec) } // Idempotent, and the union with a legacy Apps entry is deduplicated. rec.Apps = []string{"harbourmail"} if rec.AddSenderRef("harbourmail", "book.example.com") { t.Fatal("a second AddSenderRef reported a change") } want := []string{"harbourmail/app", "harbourmail/book.example.com"} if got := rec.SenderRefs(); !reflect.DeepEqual(got, want) { t.Fatalf("SenderRefs() = %q, want %q", got, want) } if !rec.RemoveSenderRef("harbourmail", "book.example.com") || rec.HasSender("harbourmail", "book.example.com") { t.Fatalf("RemoveSenderRef left the reference behind: %+v", rec) } } ``` `internal/mail/walk_lifecycle_test.go` (append): ```go // THE #271 FAILURE, REACHED THROUGH THE NEW DOOR. VerifyDomain rebinds an // identity's configuration set and then refreshes every policy that names // the domain, from the record. Walking rec.Apps would find nothing for a // domain only an instance sender holds, and the instance's policy would go // on naming no configuration set: a 554 on every send it makes. func TestRefreshPoliciesReachesASenderThatIsNotInApps(t *testing.T) { ctx, s, p, _, now := enableFixture(t) rec := &DomainRecord{ Domain: "book.example.com", Kind: KindCustom, Regions: map[string]*RegionState{"eu-west-1": {IdentityARN: "arn:aws:ses:eu-west-1:1:identity/book.example.com", ConfigSet: "carlos-bag", Status: StatusVerified}}, CreatedAt: now, } rec.AddSenderRef("harbourmail", "book.example.com") if _, err := PutDomain(ctx, s, "bag", rec, ""); err != nil { t.Fatal(err) } if _, err := DeclareInstance(ctx, s, "bag", "harbourmail", "book.example.com", "book.example.com", "HARBOURMAIL_SMTP", "hello@book.example.com", "owner@example.test", now); err != nil { t.Fatal(err) } sn, etag, err := GetSender(ctx, s, "bag", "harbourmail", "book.example.com") if err != nil { t.Fatal(err) } names, err := senderNamesOf("bag", "harbourmail", sn) if err != nil { t.Fatal(err) } sn.Provisioned = &Provisioned{IAMUser: names.IAMUser, KeyID: "AKIA9", Active: true, At: now} if _, err := PutSender(ctx, s, "bag", "harbourmail", sn, etag); err != nil { t.Fatal(err) } if err := RefreshPolicies(ctx, s, p, "bag", rec.SenderRefs()); err != nil { t.Fatal(err) } pol, ok := p.UserPolicy(names.IAMUser) if !ok { t.Fatalf("no policy written for %s; the instance sender was never refreshed", names.IAMUser) } if !strings.Contains(pol, "configuration-set/carlos-bag") { t.Fatalf("policy for %s names no configuration set, which is a 554 on every send:\n%s", names.IAMUser, pol) } } // The app sender's policy can never name a domain only an instance holds. // grantedDomains is the one function that decides this, and it now filters // on the sender rather than on the app. func TestGrantedDomainsKeepsAnInstancesDomainOutOfTheAppSendersPolicy(t *testing.T) { ctx, s, _, _, now := enableFixture(t) rec := &DomainRecord{ Domain: "book.example.com", Kind: KindCustom, Regions: map[string]*RegionState{"eu-west-1": {IdentityARN: "arn:aws:ses:eu-west-1:1:identity/book.example.com", Status: StatusVerified}}, CreatedAt: now, } rec.AddSenderRef("harbourmail", "book.example.com") if _, err := PutDomain(ctx, s, "bag", rec, ""); err != nil { t.Fatal(err) } got, err := grantedDomains(ctx, s, "bag", "harbourmail", SenderAppID) if err != nil { t.Fatal(err) } for _, d := range got { if d.Domain == "book.example.com" { t.Fatal("the app sender was granted a domain only an instance sender holds") } } got, err = grantedDomains(ctx, s, "bag", "harbourmail", "book.example.com") if err != nil || len(got) != 1 || got[0].Domain != "book.example.com" { t.Fatalf("the instance sender was not granted its own domain: %+v %v", got, err) } } ``` `MemProvisioner` needs a policy reader for the first test. If `UserPolicy(name string) (string, bool)` does not already exist on it (plan 3 leans on the same accessor for its address-policy tests), add it in `internal/mail/memprovisioner.go` returning the last policy `EnsureUser` rendered for that user. - [ ] **Step 2: Run the test — expect failure** ```bash GOCACHE=/tmp/claude-1001/gocache GOFLAGS=-mod=mod GOPROXY=off go test ./internal/mail/ -run 'TestSenderRefs|TestAddSenderRef|TestRefreshPoliciesReaches|TestGrantedDomainsKeeps' -count=1 ``` Expected: build failure, `undefined: SenderRef`, `rec.SenderRefs undefined`, and `too many arguments in call to grantedDomains`. - [ ] **Step 3: Implement** `internal/mail/domain.go`, on `DomainRecord`, beside `Apps`: ```go // Senders is every sender authorised to send from this domain, as // "/" references (design §6.3). It exists because Apps // cannot express one: an instance sender is one of many inside an app, // and an app-shaped grant would hand the app-wide credential every // sibling instance holds an identity that belongs to one customer. // // omitempty, and absent on every record written before this release — // SenderRefs reads such a record's Apps as one app-sender reference // each, so nothing needs backfilling and a rolled-back console reads // what it always read. Senders []string `json:"senders,omitempty"` ``` and, after `RemoveApp`: ```go // SenderRef is how a sender is named inside a domain record: the app, a // slash, the sender id. The slash is safe as a separator because ValidApp // forbids one and ValidSenderID forbids one. func SenderRef(app, sender string) string { return app + "/" + sender } // SplitSenderRef is SenderRef's inverse. ok is false for anything that is // not exactly one slash with a non-empty side each — a malformed reference // is skipped by every caller rather than guessed at, because guessing would // write a policy for a principal nobody named. func SplitSenderRef(ref string) (string, string, bool) { app, sender, found := strings.Cut(ref, "/") if !found || app == "" || sender == "" || strings.Contains(sender, "/") { return "", "", false } return app, sender, true } // SenderRefs is every sender this domain grants, sorted and deduplicated, // with each legacy Apps entry read as that app's APP sender. That fallback // is the whole migration: nothing rewrites a domain record, and the first // RefreshPolicies after this release must still find every principal it // found before it. func (r *DomainRecord) SenderRefs() []string { seen := map[string]bool{} var out []string add := func(ref string) { if _, _, ok := SplitSenderRef(ref); !ok || seen[ref] { return } seen[ref] = true out = append(out, ref) } for _, a := range r.Apps { add(SenderRef(a, SenderAppID)) } for _, ref := range r.Senders { add(ref) } sort.Strings(out) return out } // HasSender reports whether this domain grants one sender. func (r *DomainRecord) HasSender(app, sender string) bool { want := SenderRef(app, sender) for _, ref := range r.SenderRefs() { if ref == want { return true } } return false } // AddSenderRef records a sender as a referrer. Reports whether it changed // anything. It NEVER touches Apps: an app sender's attach calls AddApp too // (EnsureDomainForSender does both), and an instance sender's attach must // not, or grantedDomains would hand the app-wide credential a customer's // identity. func (r *DomainRecord) AddSenderRef(app, sender string) bool { if r.HasSender(app, sender) { return false } r.Senders = append(r.Senders, SenderRef(app, sender)) sort.Strings(r.Senders) return true } // RemoveSenderRef drops a referrer from Senders. An app sender recorded only // in the legacy Apps list is removed by RemoveApp, which is what // TeardownSender calls for it. func (r *DomainRecord) RemoveSenderRef(app, sender string) bool { want := SenderRef(app, sender) for i, ref := range r.Senders { if ref == want { r.Senders = append(r.Senders[:i], r.Senders[i+1:]...) return true } } return false } ``` `internal/mail/instance.go`, append: ```go // senderNamesOf recomputes one sender's AWS names from the record, and // refuses when the computed slug disagrees with the stored one. // // Recomputing rather than reading Provisioned.IAMUser is the discipline // RefreshPolicies already follows for standalone credentials, and the // refusal is what makes it safe: if the naming rule ever moved, the old // behaviour would quietly write a policy for a brand new principal and // leave the live one stale, which presents as "this sender stopped working // and nothing changed". Failing loudly here turns that into one error with // the two names in it. func senderNamesOf(acct, app string, sn *Sender) (SenderNameSet, error) { names, err := SenderNames(acct, app, sn.ID, sn.Salt) if err != nil { return SenderNameSet{}, err } if names.Slug != sn.Slug { return SenderNameSet{}, fmt.Errorf( "mail: sender %s/%s is recorded with slug %q and the naming rule now computes %q — refusing to write a policy for a principal no record names", app, sn.ID, sn.Slug, names.Slug) } return names, nil } ``` `internal/mail/walk.go`, `grantedDomains`: take `sender string` after `app`, and replace the `for _, a := range d.Apps` loop with `if d.HasSender(app, sender) { out = append(out, d) }`. Its three callers pass a sender: `Enable` and `CreateStandalone` pass `SenderAppID`, and `RefreshPolicies` passes the sender it is iterating. `internal/mail/walk.go`, `RefreshPolicies`: the parameter becomes `refs []string` and the body iterates sender references rather than apps. ```go func RefreshPolicies(ctx context.Context, s release.Store, p Provisioner, acct string, refs []string) error { for _, ref := range refs { app, sender, ok := SplitSenderRef(ref) if !ok { // A malformed reference names no principal. Skipping is the // only safe direction: inventing an app or a sender from it // would write a policy for somebody who never asked for one. log.Printf("mail: refresh policies: skipping malformed sender reference %q", ref) continue } sn, _, err := GetSender(ctx, s, acct, app, sender) if err != nil { return err } if sn == nil || sn.Declared == nil { continue } if sn.Provisioned == nil && len(sn.Standalone) == 0 { continue } domains, err := grantedDomains(ctx, s, acct, app, sender) if err != nil { return err } if len(domains) == 0 { continue } var arns, configSets, names []string for _, dom := range domains { arns = append(arns, dom.VerifiedARNs()...) configSets = append(configSets, dom.VerifiedConfigSetARNs()...) names = append(names, dom.Domain) } sort.Strings(arns) sort.Strings(configSets) sort.Strings(names) if len(arns) == 0 { // Granted domains exist but none is verified in any region, so // SendPolicyJSON would refuse anyway. Nothing to write. continue } nameSet, err := senderNamesOf(acct, app, sn) if err != nil { return err } if sn.Provisioned != nil { if _, err := p.EnsureUser(ctx, nameSet.IAMUser, UserPath, arns, configSets, names); err != nil { return fmt.Errorf("mail: refresh policy for %s: %w", nameSet.IAMUser, err) } } for _, sa := range sn.Standalone { user, err := nameSet.StandaloneUser(acct, app, sa.Name) if err != nil { return err } if _, err := p.EnsureUser(ctx, user, UserPath, arns, configSets, names); err != nil { return fmt.Errorf("mail: refresh policy for %s: %w", user, err) } } } return nil } ``` Add `"log"` to `walk.go`'s imports. `EnsureDomain`'s call becomes `RefreshPolicies(ctx, s, p, acct, rec.SenderRefs())` and `VerifyDomain`'s rebound branch the same. **An address sender's principal (plan 3) is reached through the same path.** Plan 3's `ensureAddressPrincipal` calls `EnsureAddressUser`, not `EnsureUser`, so an address sender whose policy this loop rewrote with `EnsureUser` would lose its `ses:FromAddress` condition. Guard it: skip a sender whose `Source == SourceAddress` in this loop, with the comment saying its policy is `EnsureAddressUser`'s and is rewritten by that sender's own enable. `internal/console/apimail.go`, `mailAppDomains`: replace the `for _, a := range d.Apps` loop with `if d.HasSender(app, mail.SenderAppID)`. Its doc comment gains the sentence that says why the app sender specifically: the enable door feeds this list to `ApplyGrant` for the app sender, and an instance sender's domain reaching it would put a customer's identity in the app-wide credential. - [ ] **Step 4: Run the test — expect success** ```bash GOCACHE=/tmp/claude-1001/gocache GOFLAGS=-mod=mod GOPROXY=off go test ./internal/mail/ ./internal/console/ -count=1 ``` - [ ] **Step 5: Gate and commit** ```bash gofmt -w internal/mail/domain.go internal/mail/walk.go internal/mail/instance.go internal/console/apimail.go internal/mail/domain_test.go internal/mail/walk_lifecycle_test.go GOCACHE=/tmp/claude-1001/gocache GOFLAGS=-mod=mod GOPROXY=off go build ./... && \ GOCACHE=/tmp/claude-1001/gocache GOFLAGS=-mod=mod GOPROXY=off go vet ./... && \ GOCACHE=/tmp/claude-1001/gocache GOFLAGS=-mod=mod GOPROXY=off go test ./... -count=1 && \ gofmt -l . git commit -am "mail: a domain record names senders, and both policy walks follow them (plan 5, task 2) Co-Authored-By: Claude Opus 5 " ``` --- ### Task 3: The claim carries the sender, and an instance never attaches a sibling's domain **Files:** - Modify: `internal/mail/domainclaim.go` (`DomainClaim`, `claimDomain`, `releaseDomainClaim`), `internal/mail/walk.go` (`EnsureDomain` -> `EnsureDomainForSender`, `Teardown` -> `TeardownSender`), `internal/mail/walk_domainclaim_test.go` **Interfaces:** - Consumes: `getDomainClaimETag` (`domainclaim.go:88`), `ErrDomainClaimed` (`:75`), `ListDomainClaims` (`:185`), `release.ErrCASConflict`, plan 3's `ExternalIdentityFor`/`ErrExternalIdentity` refusal that already sits before `claimDomain` in `EnsureDomain`, plan 2's `SenderAppID`, task 2's `AddSenderRef`/`RemoveSenderRef`/`SenderRefs`. - Produces: ```go // DomainClaim gains: Sender string `json:"sender,omitempty"` var ErrDomainHeldBySender = errors.New("mail: domain is held by another sender in this account") func claimDomain(ctx context.Context, s release.Store, domain, acct, app, sender string, now time.Time) error // unexported, gains sender func EnsureDomainForSender(ctx context.Context, s release.Store, p Provisioner, w dnsrec.Writer, d Deployment, acct, app, sender, domain string, now time.Time) (*DomainRecord, []dnsrec.Record, error) func EnsureDomain(...) // unchanged signature, delegates with SenderAppID func TeardownSender(ctx context.Context, s release.Store, p Provisioner, w dnsrec.Writer, d Deployment, acct, app, sender string) error func Teardown(...) // unchanged signature, delegates with SenderAppID ``` - [ ] **Step 1: Write the failing test** `internal/mail/walk_domainclaim_test.go` (append): ```go // THE HOLE §6.4 CLOSES. Two instances of one app, in one account. The // second attaches the first's already-verified domain, and today the claim // says yes (same account, so the re-claim is a silent no-op) and the second // instance inherits an identity it proved nothing about. func TestClaimDomainRefusesAnotherSendersDomainInsideOneAccount(t *testing.T) { ctx := context.Background() s := release.NewDirStore(t.TempDir()) now := time.Date(2026, 9, 15, 12, 0, 0, 0, time.UTC) if err := claimDomain(ctx, s, "book.example.com", "bag", "harbourmail", "book.example.com", now); err != nil { t.Fatal(err) } // The same sender re-claiming is idempotent success: EnsureDomain is // re-run on every attach and must never be refused by the gate it holds. if err := claimDomain(ctx, s, "book.example.com", "bag", "harbourmail", "book.example.com", now); err != nil { t.Fatalf("a re-claim by the holder was refused: %v", err) } // A sibling instance of the same app, in the same account, is refused. if err := claimDomain(ctx, s, "book.example.com", "bag", "harbourmail", "shop.example.com", now); !errors.Is(err, ErrDomainHeldBySender) { t.Fatalf("a sibling instance's claim = %v, want ErrDomainHeldBySender", err) } // So is the app sender of the same app, and a second app in the account. if err := claimDomain(ctx, s, "book.example.com", "bag", "harbourmail", SenderAppID, now); !errors.Is(err, ErrDomainHeldBySender) { t.Fatalf("the app sender's claim = %v, want ErrDomainHeldBySender", err) } if err := claimDomain(ctx, s, "book.example.com", "bag", "keymail", SenderAppID, now); !errors.Is(err, ErrDomainHeldBySender) { t.Fatalf("a second app's claim = %v, want ErrDomainHeldBySender", err) } // Another account is still the neutral refusal that never names a holder. if err := claimDomain(ctx, s, "book.example.com", "jam", "jelly", SenderAppID, now); !errors.Is(err, ErrDomainClaimed) { t.Fatalf("a stranger's claim = %v, want ErrDomainClaimed", err) } } // A claim written before this release carries no Sender. It belongs to that // app's APP sender, which is the only sender that existed, so a re-attach by // that app keeps working and nothing in the fleet has to be backfilled. func TestALegacyClaimBelongsToTheAppSender(t *testing.T) { ctx := context.Background() s := release.NewDirStore(t.TempDir()) now := time.Date(2026, 9, 15, 12, 0, 0, 0, time.UTC) body, err := json.Marshal(DomainClaim{Schema: 1, Domain: "x.com", Account: "bag", App: "harbourmail", CreatedAt: now}) if err != nil { t.Fatal(err) } if _, err := s.Put(ctx, domainClaimKey("x.com"), body, ""); err != nil { t.Fatal(err) } if err := claimDomain(ctx, s, "x.com", "bag", "harbourmail", SenderAppID, now); err != nil { t.Fatalf("a legacy claim refused its own app sender: %v", err) } if err := claimDomain(ctx, s, "x.com", "bag", "harbourmail", "book.example.com", now); !errors.Is(err, ErrDomainHeldBySender) { t.Fatalf("an instance sender took a legacy app claim: %v", err) } } // EnsureDomainForSender records an instance sender in Senders and never in // Apps, and the orphan-claim sweep in TeardownSender only ever releases a // claim THIS sender created. func TestEnsureDomainForSenderRecordsTheSenderAndSweepsOnlyItsOwnOrphan(t *testing.T) { ctx, s, p, _, now := enableFixture(t) rec, _, err := EnsureDomainForSender(ctx, s, p, dnsrec.NewMemWriter(), testDeployment(), "bag", "harbourmail", "book.example.com", "book.example.com", now) if err != nil { t.Fatal(err) } if len(rec.Apps) != 0 { t.Fatalf("an instance sender's attach joined Apps: %q", rec.Apps) } if !rec.HasSender("harbourmail", "book.example.com") { t.Fatalf("the sender was not recorded: %+v", rec) } // An orphan this sender never created survives its teardown. if err := claimDomain(ctx, s, "shop.example.com", "bag", "harbourmail", "shop.example.com", now); err != nil { t.Fatal(err) } if err := TeardownSender(ctx, s, p, dnsrec.NewMemWriter(), testDeployment(), "bag", "harbourmail", "book.example.com"); err != nil { t.Fatal(err) } got, err := getDomainClaim(ctx, s, "shop.example.com") if err != nil || got == nil { t.Fatalf("a sibling sender's orphan claim was swept: %+v %v", got, err) } if got, err := getDomainClaim(ctx, s, "book.example.com"); err != nil || got != nil { t.Fatalf("this sender's own claim survived its teardown: %+v %v", got, err) } } ``` - [ ] **Step 2: Run the test — expect failure** ```bash GOCACHE=/tmp/claude-1001/gocache GOFLAGS=-mod=mod GOPROXY=off go test ./internal/mail/ -run 'TestClaimDomainRefuses|TestALegacyClaim|TestEnsureDomainForSender' -count=1 ``` Expected: build failure, `not enough arguments in call to claimDomain`, `undefined: ErrDomainHeldBySender`, `undefined: EnsureDomainForSender`, `undefined: TeardownSender`. - [ ] **Step 3: Implement** `internal/mail/domainclaim.go`, on `DomainClaim`, after `App`: ```go // Sender is the sender that holds the claim, inside App. omitempty, // and absent on every claim written before this release: an empty // Sender reads as SenderAppID, because the app sender is the only // sender that existed when such a claim was written. Nothing is // backfilled and a rolled-back console reads what it always read. Sender string `json:"sender,omitempty"` ``` and a new error beside `ErrDomainClaimed`: ```go // ErrDomainHeldBySender is a claim on a domain this ACCOUNT already holds, // through a different sender. It names no holder either, for the same // reason ErrDomainClaimed names none, and it is deliberately a different // error so the console can say "another app or instance in this account" // rather than the cross-account sentence, which would be a lie. // // This is a behaviour change (design §6.4): before it, any re-claim by the // holder's own account was a silent no-op, which is how two apps in one // account came to share a domain, and is also how one instance sender would // have attached a sibling's already-verified identity with no proof of its // own. Domains already attached keep working — this only ever fires on a new // attach. var ErrDomainHeldBySender = errors.New("mail: domain is held by another sender in this account") ``` `claimDomain` takes `sender string` after `app` and writes it into the body. Its judging tail becomes: ```go if cur.Account != acct { return ErrDomainClaimed } // An empty Sender on a stored claim is the app sender: that is the // only sender that existed when it was written. held := cur.Sender if held == "" { held = SenderAppID } if cur.App != app || held != sender { return ErrDomainHeldBySender } return nil // already ours: idempotent no-op ``` `internal/mail/walk.go`: rename `EnsureDomain`'s body to `EnsureDomainForSender` with `sender string` after `app`, and leave `EnsureDomain` as the app-sender wrapper. Inside it, four changes and nothing else: ```go // EnsureDomain is EnsureDomainForSender for the app sender. Every caller // outside this package still calls this, so the whole console and CLI are // untouched by senders existing. func EnsureDomain(ctx context.Context, s release.Store, p Provisioner, w dnsrec.Writer, d Deployment, acct, app, domain string, now time.Time) (*DomainRecord, []dnsrec.Record, error) { return EnsureDomainForSender(ctx, s, p, w, d, acct, app, SenderAppID, domain, now) } ``` - the claim call becomes `claimDomain(ctx, s, domain, acct, app, sender, now)`, and the wrap gains a second branch so `ErrDomainHeldBySender` survives `errors.Is` for the door; - `rec.AddApp(app)` becomes: ```go // The APP sender joins Apps as well as Senders, because Apps is what a // console rolled back to the previous release reads, and because // RemoveApp is still how an app sender leaves. An INSTANCE sender joins // Senders alone: Apps is what grantedDomains computes the app-wide // credential's policy from, and a customer's identity reaching it would // be delivered to every sibling instance (design §6.3). if sender == SenderAppID { rec.AddApp(app) } rec.AddSenderRef(app, sender) ``` - `RefreshPolicies(ctx, s, p, acct, rec.Apps)` is already `rec.SenderRefs()` from task 2; - the platform-name ownership check and plan 3's external-identity refusal are untouched, and both still run before the claim. `internal/mail/walk.go`, `Teardown` -> `TeardownSender` with `sender string`, and `Teardown` as the app-sender wrapper. Four changes inside: - the principal loop reads the SENDER, not the record: `GetSender(ctx, s, acct, app, sender)`, then `DeleteUser` on its `Provisioned.IAMUser` and on each `Standalone.IAMUser`; - the domain loop's `cur.RemoveApp(app)` becomes `changed := cur.RemoveSenderRef(app, sender); if sender == SenderAppID { changed = cur.RemoveApp(app) || changed }`, and `if len(cur.Apps) > 0` becomes `if len(cur.SenderRefs()) > 0` — a domain is destroyed only when the LAST sender referencing it goes, which is the same rule one level down; - the orphan-claim sweep's `if c.Account != acct || c.App != app` gains the sender: a claim's empty `Sender` reads as `SenderAppID`, so `TeardownSender(…, SenderAppID)` still sweeps a legacy orphan and an instance teardown never touches one; - the final `s.Delete(ctx, Key(acct, app))` becomes `s.Delete(ctx, SenderKey(acct, app, sender))`, so an instance teardown deletes its own sender object and the app sender's teardown deletes `senders/app.json` exactly as it deletes the record today. **Plan 3's address branch stays where it is.** `TeardownSender` keeps plan 3's `teardownAddressSender` call on the `Source == SourceAddress` path and keeps its rule of never calling `DeleteIdentity` for a borrowed identity. This task only widens who the teardown is *for*. - [ ] **Step 4: Run the test — expect success** ```bash GOCACHE=/tmp/claude-1001/gocache GOFLAGS=-mod=mod GOPROXY=off go test ./internal/mail/ ./internal/console/ -count=1 ``` - [ ] **Step 5: Gate and commit** ```bash gofmt -w internal/mail/domainclaim.go internal/mail/walk.go internal/mail/walk_domainclaim_test.go GOCACHE=/tmp/claude-1001/gocache GOFLAGS=-mod=mod GOPROXY=off go build ./... && \ GOCACHE=/tmp/claude-1001/gocache GOFLAGS=-mod=mod GOPROXY=off go vet ./... && \ GOCACHE=/tmp/claude-1001/gocache GOFLAGS=-mod=mod GOPROXY=off go test ./... -count=1 && \ gofmt -l . git commit -am "mail: the domain claim carries its sender, and refuses a sibling's re-claim (plan 5, task 3) Co-Authored-By: Claude Opus 5 " ``` --- ### Task 4: Entering and leaving per-instance mode **Files:** - Modify: `internal/mail/instance.go`, `internal/mail/walk.go` (`Enable`'s refusal), `internal/mail/instance_test.go` **Interfaces:** - Consumes: plan 2's `GetSender`/`PutSender`, `PauseKindPerInstance`, `ErrPerInstance`, `SetSenderPaused`, `Sender.PerInstance`; `Provisioner.ReapKeys` (`provisioner.go`), `EnvNames` (`envnames.go`), plan 3's `EnvNamesAddress` and `SourceAddress`, `appconfig.Apply` (`internal/appconfig/generation.go:119`), `senderNamesOf` (task 2). - Produces: ```go func EnterPerInstance(ctx context.Context, s release.Store, p Provisioner, acct, app string, now time.Time) (*Sender, error) func LeavePerInstance(ctx context.Context, s release.Store, acct, app string, now time.Time) (*Sender, error) var ErrNotPerInstance = errors.New("mail: this app is not in per-instance mode") func appSenderEnvUnsets(sn *Sender) []string // unexported ``` - [ ] **Step 1: Write the failing test** `internal/mail/instance_test.go` (append): ```go // The transition is one CAS write, then a reap, then the unset. Order // matters: the flag has to be durable before any key is destroyed, or a // crash between the two leaves an app with no credential and no record // saying why. func TestEnterPerInstanceStampsTheFlagReapsAndUnsets(t *testing.T) { ctx, s, p, pub, now := enableFixture(t) if _, err := Enable(ctx, s, p, pub, testDeployment(), "bag", "harbourmail", now); err != nil { t.Fatal(err) } if _, err := CreateStandalone(ctx, s, p, testDeployment(), "bag", "harbourmail", "laptop", "o@example.test", now); err != nil { t.Fatal(err) } sn, err := EnterPerInstance(ctx, s, p, "bag", "harbourmail", now) if err != nil { t.Fatal(err) } if !sn.PerInstance || sn.Provisioned.Active || sn.Provisioned.PauseKind != PauseKindPerInstance { t.Fatalf("the transition did not stamp the app sender: %+v", sn.Provisioned) } // DELETED, not deactivated. An enable racing the transition mints and // DELIVERS before its own CAS Put, so deactivating the ids the record // names would leave an active key nothing ever reaps in every // instance's bundle (design §6.3). names, err := senderNamesOf("bag", "harbourmail", sn) if err != nil { t.Fatal(err) } if keys := p.Keys(names.IAMUser); len(keys) != 0 { t.Fatalf("the app sender still holds %d keys after the transition", len(keys)) } saUser, err := names.StandaloneUser("bag", "harbourmail", "laptop") if err != nil { t.Fatal(err) } if keys := p.Keys(saUser); len(keys) != 0 { t.Fatalf("the standalone credential still holds %d keys after the transition", len(keys)) } // And the app's own bundle no longer carries a credential for anyone. man, err := appconfig.Get(ctx, s, "bag", "harbourmail") if err != nil { t.Fatal(err) } for _, name := range appSenderEnvUnsets(sn) { if _, ok := man.Vars[name]; ok { t.Errorf("%s is still delivered to every instance of this app", name) } } } // THE RACE §6.3 NAMES. An enable that has already minted and delivered, // interleaved with the transition, must leave no usable credential: the // reap deletes whatever keys exist, so the delivered variables are inert // even though they landed. func TestAnEnableRacingTheTransitionLeavesNoUsableAppCredential(t *testing.T) { ctx, s, p, pub, now := enableFixture(t) if _, err := Enable(ctx, s, p, pub, testDeployment(), "bag", "harbourmail", now); err != nil { t.Fatal(err) } sn, _, err := GetSender(ctx, s, "bag", "harbourmail", SenderAppID) if err != nil { t.Fatal(err) } names, err := senderNamesOf("bag", "harbourmail", sn) if err != nil { t.Fatal(err) } // The racing enable's half: a key minted and delivered, with no record // naming it yet, exactly as walk.go mints and writes before its Put. keyID, secret, err := p.MintKey(ctx, names.IAMUser) if err != nil { t.Fatal(err) } if err := writeSMTPEnv(ctx, s, pub, "bag", "harbourmail", "HARBOURMAIL_SMTP", testDeployment().Region, keyID, secret, sn.Declared.From, sn); err != nil { t.Fatal(err) } if _, err := EnterPerInstance(ctx, s, p, "bag", "harbourmail", now); err != nil { t.Fatal(err) } if keys := p.Keys(names.IAMUser); len(keys) != 0 { t.Fatalf("the unrecorded key the racing enable minted survived: %q", keys) } } // Re-entering converges rather than refusing: a crash between the CAS and // the reap has to be repairable by running the transition again. func TestEnterPerInstanceIsIdempotent(t *testing.T) { ctx, s, p, pub, now := enableFixture(t) if _, err := Enable(ctx, s, p, pub, testDeployment(), "bag", "harbourmail", now); err != nil { t.Fatal(err) } if _, err := EnterPerInstance(ctx, s, p, "bag", "harbourmail", now); err != nil { t.Fatal(err) } if _, err := EnterPerInstance(ctx, s, p, "bag", "harbourmail", now); err != nil { t.Fatalf("a second transition was refused: %v", err) } // The app sender's own enable is refused under the flag: carrying the // false Active forward would mint a key that is dead on arrival. if _, err := Enable(ctx, s, p, pub, testDeployment(), "bag", "harbourmail", now); !errors.Is(err, ErrPerInstance) { t.Fatalf("Enable in per-instance mode = %v, want ErrPerInstance", err) } // Leaving clears all three, and only then does Enable work again. sn, err := LeavePerInstance(ctx, s, "bag", "harbourmail", now) if err != nil { t.Fatal(err) } if sn.PerInstance || !sn.Provisioned.Active || sn.Provisioned.PauseKind != "" { t.Fatalf("leaving left the app sender in %+v", sn.Provisioned) } if _, err := Enable(ctx, s, p, pub, testDeployment(), "bag", "harbourmail", now); err != nil { t.Fatalf("Enable after leaving per-instance mode: %v", err) } } ``` `MemProvisioner` needs `Keys(user string) []string`, the live key ids for a principal. Add it if plan 2's reap tests did not. - [ ] **Step 2: Run the test — expect failure** ```bash GOCACHE=/tmp/claude-1001/gocache GOFLAGS=-mod=mod GOPROXY=off go test ./internal/mail/ -run 'PerInstance' -count=1 ``` Expected: build failure, `undefined: EnterPerInstance`, `undefined: LeavePerInstance`, `undefined: appSenderEnvUnsets`. - [ ] **Step 3: Implement** `internal/mail/instance.go`, append: ```go // ErrNotPerInstance is an instance verb against an app that never entered // per-instance mode. Instance Enable requires the flag, because until it is // set every instance of this app is still holding the app-wide credential, // and a per-instance credential delivered alongside it would isolate // nothing. var ErrNotPerInstance = errors.New("mail: this app is not in per-instance mode") // appSenderEnvUnsets is every variable the APP sender delivers into the // default bundle: the five SMTP names, plus plan 3's configuration-set and // tenant names when this sender sends under a borrowed identity. Computed // from the sender rather than assumed, because an address sender that kept // two variables standing would leave every instance of the app naming // CARLOS's configuration set with no credential to go with it. func appSenderEnvUnsets(sn *Sender) []string { if sn == nil || sn.Declared == nil { return nil } host, port, user, pass, from := EnvNames(sn.Declared.EnvPrefix) out := []string{host, port, user, pass, from} if sn.Source == SourceAddress { configSet, tenant := EnvNamesAddress(sn.Declared.EnvPrefix) out = append(out, configSet, tenant) } sort.Strings(out) return out } // EnterPerInstance moves an app from one shared credential to one per // instance (design §6.3). The order is the whole of its correctness: // // 1. ONE CAS write on senders/app.json that sets PerInstance, Active = // false and PauseKind = PauseKindPerInstance together. A prefix listing // cannot decide this without racing an app-sender enable, and the three // fields must land together or a status read between them would report // a state that was never intended. PauseKindPerInstance is what stops // resumeStaleCapPause re-arming the credential every instance still // holds on the next UTC day roll. // 2. ReapKeys(user, nil) on the app sender's principal and on every // standalone principal. LIST AND DELETE, never SetKeyActive on the ids // the record names: Enable mints and DELIVERS a key before its own CAS // Put, so an enable racing this transition leaves an active key in // every instance's bundle that no record names and nothing would ever // reap. Deleting whatever keys exist makes that delivery inert. // 3. Unset the app sender's variables from the default bundle, so an // instance that keeps running is left with nothing rather than with a // credential that has been silently destroyed underneath it. // // Idempotent by construction: re-entering skips the CAS when the flag is // already set and re-runs the reap and the unset, so a crash anywhere in // the sequence is repaired by running it again. Instance Enable re-runs // step 2 for the same reason. func EnterPerInstance(ctx context.Context, s release.Store, p Provisioner, acct, app string, now time.Time) (*Sender, error) { sn, etag, err := GetSender(ctx, s, acct, app, SenderAppID) if err != nil { return nil, err } if sn == nil || sn.Declared == nil { return nil, ErrNotDeclared } if !sn.PerInstance { sn.PerInstance = true if sn.Provisioned != nil { sn.Provisioned.Active = false sn.Provisioned.PauseKind = PauseKindPerInstance sn.Provisioned.At = now } if _, err := PutSender(ctx, s, acct, app, sn, etag); err != nil { return nil, err } } names, err := senderNamesOf(acct, app, sn) if err != nil { return nil, err } users := []string{} if sn.Provisioned != nil { users = append(users, names.IAMUser) } for _, sa := range sn.Standalone { user, err := names.StandaloneUser(acct, app, sa.Name) if err != nil { return nil, err } users = append(users, user) } for _, user := range users { if err := p.ReapKeys(ctx, user, nil); err != nil { return nil, fmt.Errorf("mail: reap keys for %s: %w", user, err) } } if unsets := appSenderEnvUnsets(sn); len(unsets) > 0 { if _, err := appconfig.Apply(ctx, s, acct, app, nil, unsets); err != nil { return nil, err } } return sn, nil } // LeavePerInstance is the inverse, and it is ONLY the record half: it clears // PerInstance, sets Active and clears PauseKind in one CAS, and the caller // runs a normal Enable afterwards. Splitting it that way is deliberate — // Enable carries Active forward from the record, so an enable under a false // Active would mint a key that is disabled at IAM the moment it is made, and // the delivered credential would fail SMTP auth with nothing to point at. // // It takes no Provisioner, because it destroys nothing and arms nothing. func LeavePerInstance(ctx context.Context, s release.Store, acct, app string, now time.Time) (*Sender, error) { sn, etag, err := GetSender(ctx, s, acct, app, SenderAppID) if err != nil { return nil, err } if sn == nil || sn.Declared == nil { return nil, ErrNotDeclared } if !sn.PerInstance { return sn, nil // already out: idempotent, like entering } sn.PerInstance = false if sn.Provisioned != nil { sn.Provisioned.Active = true sn.Provisioned.PauseKind = "" sn.Provisioned.At = now } if _, err := PutSender(ctx, s, acct, app, sn, etag); err != nil { return nil, err } return sn, nil } ``` `internal/mail/walk.go`, `Enable`: immediately after the `rec == nil || rec.Declared == nil` check, refuse under the flag. ```go // Refused UNDER THE ETAG THIS READ RETURNED (design §6.3): the record // this walk goes on to Put is the one it just read, so a transition // that lands after this check still loses the CAS and this enable never // delivers a credential the transition is busy destroying. if rec.PerInstance() { return nil, ErrPerInstance } ``` `Record` is the app sender's in-memory view (plan 2), so it needs a `PerInstance()` passthrough beside the `sender()` one plan 2 added, rather than a field: `Record`'s wire shape is `email.json`'s and must not grow. **If plan 2's task 12 already added this refusal, leave it alone** and make this task's assertion the only change. Check `Enable` first; the plan-2 header says the flag's refusals were written there against a hand-set flag, and the `SetPaused`/`resumeStaleCapPause` pair certainly were. - [ ] **Step 4: Run the test — expect success** ```bash GOCACHE=/tmp/claude-1001/gocache GOFLAGS=-mod=mod GOPROXY=off go test ./internal/mail/ -count=1 ``` - [ ] **Step 5: Gate and commit** ```bash gofmt -w internal/mail/instance.go internal/mail/walk.go internal/mail/instance_test.go internal/mail/memprovisioner.go GOCACHE=/tmp/claude-1001/gocache GOFLAGS=-mod=mod GOPROXY=off go build ./... && \ GOCACHE=/tmp/claude-1001/gocache GOFLAGS=-mod=mod GOPROXY=off go vet ./... && \ GOCACHE=/tmp/claude-1001/gocache GOFLAGS=-mod=mod GOPROXY=off go test ./... -count=1 && \ gofmt -l . git commit -am "mail: enter and leave per-instance mode (plan 5, task 4) Co-Authored-By: Claude Opus 5 " ``` --- ### Task 5: `EnableInstance`, and the credential that only one instance can read **Files:** - Modify: `internal/mail/instance.go`, `internal/mail/instance_test.go` **Interfaces:** - Consumes: plan 4's `appconfig.ApplyInstance(ctx, s, acct, app, host, sets, unsets) (removed int, etag string, err error)` and `appconfig.LoadInstanceConfig(ctx, s, acct, app, host) (*Manifest, string, bool, error)`; plan 2's `ResolveSenderNames`, `SenderNameSet`, `GetSender`/`PutSender`, `ConfigSetARN`, `AssociateTenantResource`; `SMTPHost`/`SMTPPort`/`SMTPPassword`, `EnvNames`, `UserPath`, `enforceKeyActive` (`walk.go:848`), `appconfig.Seal`, `appconfig.ValidVarValue`, `Provisioner.{EnsureTenant,EnsureUser,ReapKeys,MintKey}`, task 2's `grantedDomains`, task 4's `ErrNotPerInstance`. - Produces: ```go func EnableInstance(ctx context.Context, s release.Store, p Provisioner, sealPub *ecdh.PublicKey, d Deployment, acct, app, sender string, now time.Time) (*Sender, string, error) // sender, instance-overlay etag func EnvDeliveredInstance(ctx context.Context, s release.Store, acct, app string, sn *Sender, wantKeyID string) ([]string, error) func writeSMTPEnvInstance(ctx context.Context, s release.Store, sealPub *ecdh.PublicKey, acct, app string, sn *Sender, region, keyID, secret string) (string, error) // unexported ``` **The policy carries no tenant condition, and that is plan 3's ruling, not a gap.** `SendPolicyJSON` renders the domain form with no `ses:TenantName` condition because nothing delivers `

_TENANT` to a domain sender, and a condition on a header the app never sets is 554 on every send. An instance sender on its own custom domain is isolated by the `ses:FromAddress` condition and by `grantedDomains` naming only that sender's domains — the app-wide credential is gone by then anyway (task 4). The tenant is still created and associated, because §8 counts and pauses per tenant and because an association is what lets a later release adopt `UpdateReputationEntityCustomerManagedStatus` as the pause verb. `SetKeyActive` stays the pause verb for this release, exactly as plan 2 ruled. - [ ] **Step 1: Write the failing test** `internal/mail/instance_test.go` (append): ```go // The credential goes into the instance layer and NOWHERE else. This is // the whole point of the feature: the default bundle is what every sibling // renders, so a variable landing there is a credential handed to every // customer of a multi-tenant app. func TestEnableInstanceDeliversOnlyIntoTheInstanceLayer(t *testing.T) { ctx, s, p, pub, now := instanceEnableFixture(t) sn, etag, err := EnableInstance(ctx, s, p, pub, testDeployment(), "bag", "harbourmail", "book.example.com", now) if err != nil { t.Fatal(err) } if etag == "" { t.Fatal("EnableInstance returned no overlay etag, so no door can ever confirm delivery") } if sn.Provisioned == nil || sn.Provisioned.KeyID == "" { t.Fatalf("no credential was recorded: %+v", sn.Provisioned) } over, gotEtag, found, err := appconfig.LoadInstanceConfig(ctx, s, "bag", "harbourmail", "book.example.com") if err != nil || !found { t.Fatalf("no instance overlay was written: %v %v", found, err) } if gotEtag != etag { t.Fatalf("overlay etag = %q, EnableInstance returned %q", gotEtag, etag) } host, port, user, pass, from := EnvNames("HARBOURMAIL_SMTP") for _, name := range []string{host, port, user, from} { if v, ok := over.Vars[name]; !ok || v.Kind != "env" { t.Errorf("%s is not delivered into the overlay as env: %+v", name, v) } } if v, ok := over.Vars[pass]; !ok || v.Kind != "secret" { t.Errorf("%s is not sealed into the overlay: %+v", pass, v) } if over.Vars[user].Value != sn.Provisioned.KeyID { t.Errorf("the delivered key id %q is not the one the record names %q", over.Vars[user].Value, sn.Provisioned.KeyID) } // The default bundle carries none of it. man, err := appconfig.Get(ctx, s, "bag", "harbourmail") if err != nil { t.Fatal(err) } for _, name := range []string{host, port, user, pass, from} { if _, ok := man.Vars[name]; ok { t.Errorf("%s reached the default bundle, so every sibling instance can read this customer's credential", name) } } // Idempotent: a second enable with delivery intact mints nothing new. again, _, err := EnableInstance(ctx, s, p, pub, testDeployment(), "bag", "harbourmail", "book.example.com", now) if err != nil { t.Fatal(err) } if again.Provisioned.KeyID != sn.Provisioned.KeyID { t.Fatalf("a healthy re-enable minted a new key %q -> %q", sn.Provisioned.KeyID, again.Provisioned.KeyID) } } // An instance sender needs the app to be in per-instance mode first, and // only the app's own doors can put it there. Enabling one without it would // deliver a per-instance credential alongside the app-wide one every // sibling still holds, which isolates nothing. func TestEnableInstanceRequiresPerInstanceMode(t *testing.T) { ctx, s, p, pub, now := instanceEnableFixture(t) sn, etag, err := GetSender(ctx, s, "bag", "harbourmail", SenderAppID) if err != nil { t.Fatal(err) } sn.PerInstance = false if _, err := PutSender(ctx, s, "bag", "harbourmail", sn, etag); err != nil { t.Fatal(err) } if _, _, err := EnableInstance(ctx, s, p, pub, testDeployment(), "bag", "harbourmail", "book.example.com", now); !errors.Is(err, ErrNotPerInstance) { t.Fatalf("EnableInstance outside per-instance mode = %v, want ErrNotPerInstance", err) } } // The From address must be at one of THIS sender's verified domains, not at // any domain the app holds. Otherwise the ses:FromAddress condition refuses // every send at runtime, which presents as "email silently does not work". func TestEnableInstanceRefusesAFromOutsideItsOwnDomains(t *testing.T) { ctx, s, p, pub, now := instanceEnableFixture(t) sn, etag, err := GetSender(ctx, s, "bag", "harbourmail", "book.example.com") if err != nil { t.Fatal(err) } sn.Declared.From = "hello@shop.example.com" if _, err := PutSender(ctx, s, "bag", "harbourmail", sn, etag); err != nil { t.Fatal(err) } _, _, err = EnableInstance(ctx, s, p, pub, testDeployment(), "bag", "harbourmail", "book.example.com", now) if err == nil || !strings.Contains(err.Error(), "is not at any verified domain") { t.Fatalf("EnableInstance with a foreign From = %v", err) } } ``` `instanceEnableFixture` is the state an instance enable expects: an app sender declared, enabled and then moved into per-instance mode, plus one instance sender declared with a verified domain of its own attached through `EnsureDomainForSender`. Write it beside the tests, using `enableFixture` for the first half and task 3's `EnsureDomainForSender` plus `VerifyDomain` for the second. - [ ] **Step 2: Run the test — expect failure** ```bash GOCACHE=/tmp/claude-1001/gocache GOFLAGS=-mod=mod GOPROXY=off go test ./internal/mail/ -run EnableInstance -count=1 ``` Expected: build failure, `undefined: EnableInstance`. - [ ] **Step 3: Implement** `internal/mail/instance.go`, append: ```go // EnvDeliveredInstance is EnvDelivered for one instance sender, and it // reads the OVERLAY ALONE, never the merged view. // // That is the whole difference and it is load-bearing. A merged read would // let a value standing in the app's default bundle satisfy this check, so // an instance whose overlay was never written would report delivered while // running on a credential that belongs to the app, or to nobody. The // overlay is the only layer this sender writes, so it is the only layer // that can answer for it. func EnvDeliveredInstance(ctx context.Context, s release.Store, acct, app string, sn *Sender, wantKeyID string) ([]string, error) { man, _, found, err := appconfig.LoadInstanceConfig(ctx, s, acct, app, sn.Host) if err != nil { return nil, err } host, port, user, pass, from := EnvNames(sn.Declared.EnvPrefix) if !found { out := []string{host, port, user, pass, from} sort.Strings(out) return out, nil } var missing []string check := func(name, wantKind string) { v, ok := man.Vars[name] if !ok || v.Kind != wantKind { missing = append(missing, name) } } check(host, "env") check(port, "env") check(pass, "secret") // _USER's VALUE is compared for EnvDelivered's own reason: it is the // one credential half delivered unsealed, so a failed final Put after a // successful mint and deliver is catchable here and nowhere else. if v, ok := man.Vars[user]; !ok || v.Kind != "env" || (wantKeyID != "" && v.Value != wantKeyID) { missing = append(missing, user) } if v, ok := man.Vars[from]; !ok || v.Kind != "env" || v.Value != sn.Declared.From { missing = append(missing, from) } sort.Strings(missing) return missing, nil } // writeSMTPEnvInstance delivers the five variables into the instance layer // and returns that layer's new etag, which is what makes delivery // confirmable: the console compares it against the etag the agent's ack // says it rendered (design §6.5). Every validation writeSMTPEnv performs // happens here too, and for the same reasons — a sealed value reaches // appconfig as an opaque envelope, so an unrenderable byte would stall this // instance's whole config render hours later and out of sight. func writeSMTPEnvInstance(ctx context.Context, s release.Store, sealPub *ecdh.PublicKey, acct, app string, sn *Sender, region, keyID, secret string) (string, error) { hostName, portName, userName, passName, fromName := EnvNames(sn.Declared.EnvPrefix) password := SMTPPassword(secret, region) if err := appconfig.ValidVarValue(keyID); err != nil { return "", fmt.Errorf("mail: minted credential for %s is not EnvironmentFile-safe: %w", userName, err) } if err := appconfig.ValidVarValue(password); err != nil { return "", fmt.Errorf("mail: minted credential for %s is not EnvironmentFile-safe: %w", passName, err) } env, err := appconfig.Seal(sealPub, []byte(password)) if err != nil { return "", fmt.Errorf("mail: seal %s: %w", passName, err) } sets := map[string]appconfig.Var{ hostName: {Kind: "env", Value: SMTPHost(region)}, portName: {Kind: "env", Value: SMTPPort}, userName: {Kind: "env", Value: keyID}, passName: {Kind: "secret", Value: env}, fromName: {Kind: "env", Value: sn.Declared.From}, } _, etag, err := appconfig.ApplyInstance(ctx, s, acct, app, sn.Host, sets, nil) return etag, err } // EnableInstance provisions one instance sender's credential and delivers // it into that instance's own config layer. It is Enable's counterpart and // keeps every one of Enable's rules, with three additions: // // - the app must be in per-instance mode, or this credential would be // delivered alongside the app-wide one every sibling still holds; // - the app sender's keys are reaped again, because an app enable that // raced the transition may have minted and delivered one since; // - the delivered variables go through the instance layer, and the // layer's new etag comes back so the caller can confirm delivery. // // The second return value is that etag, and it is "" only when nothing was // written, which is the idempotent short-circuit. func EnableInstance(ctx context.Context, s release.Store, p Provisioner, sealPub *ecdh.PublicKey, d Deployment, acct, app, sender string, now time.Time) (*Sender, string, error) { appSender, _, err := GetSender(ctx, s, acct, app, SenderAppID) if err != nil { return nil, "", err } if appSender == nil || appSender.Declared == nil { return nil, "", ErrNotDeclared } if !appSender.PerInstance { return nil, "", ErrNotPerInstance } sn, etag, err := GetSender(ctx, s, acct, app, sender) if err != nil { return nil, "", err } if sn == nil || sn.Declared == nil { return nil, "", ErrNotDeclared } if sn.Scope != ScopeInstance { return nil, "", ErrNotInstanceSender } domains, err := grantedDomains(ctx, s, acct, app, sender) if err != nil { return nil, "", err } if len(domains) == 0 { return nil, "", ErrNoDomains } var arns, configSets, names []string for _, dom := range domains { arns = append(arns, dom.VerifiedARNs()...) configSets = append(configSets, dom.VerifiedConfigSetARNs()...) names = append(names, dom.Domain) } sort.Strings(arns) sort.Strings(configSets) sort.Strings(names) at := strings.LastIndex(sn.Declared.From, "@") if !containsString(names, sn.Declared.From[at+1:]) { return nil, "", fmt.Errorf("mail: From %q is not at any verified domain (%s)", sn.Declared.From, strings.Join(names, ", ")) } // The names and the caller index together: ResolveSenderNames writes // email/callers/.json right after this, which is what makes a // slugged caller resolvable back to this sender when SES stamps it on // an event. Nothing parses a slug back. nameSet, _, err := ResolveSenderNames(ctx, s, acct, app, sn, now) if err != nil { return nil, "", err } // This sender's own tenant, associated with the account's configuration // set and with each identity it may send from. The tenant is what makes // this sender's events and its future pause its own (design §8); the // policy carries no tenant condition, because a domain sender is never // delivered a tenant header to satisfy one with. if err := p.EnsureTenant(ctx, nameSet.Tenant); err != nil { return nil, "", fmt.Errorf("mail: ensure tenant %s: %w", nameSet.Tenant, err) } for _, arn := range append(append([]string{}, arns...), configSets...) { if err := p.AssociateTenantResource(ctx, nameSet.Tenant, arn); err != nil { return nil, "", fmt.Errorf("mail: associate %s with tenant %s: %w", arn, nameSet.Tenant, err) } } // EnsureUser runs unconditionally, before the short-circuit, for C2's // reason: it is the only place this sender's policy is written, and the // grant above is recomputed from the CURRENT domain set on every call. userARN, err := p.EnsureUser(ctx, nameSet.IAMUser, UserPath, arns, configSets, names) if err != nil { return nil, "", fmt.Errorf("mail: ensure user %s: %w", nameSet.IAMUser, err) } if sn.Provisioned != nil { missing, err := EnvDeliveredInstance(ctx, s, acct, app, sn, sn.Provisioned.KeyID) if err != nil { return nil, "", err } if len(missing) == 0 { return sn, "", nil } } // Re-run the app sender's reap (design §6.3). An app enable that raced // the transition mints and delivers before its own CAS Put, so a key // with no record naming it can appear after the transition has already // swept. This is the second sweep that makes such a key inert. if _, err := EnterPerInstance(ctx, s, p, acct, app, now); err != nil { return nil, "", err } active, prev, pauseKind := true, "", "" if sn.Provisioned != nil { prev, active, pauseKind = sn.Provisioned.PrevKeyID, sn.Provisioned.Active, sn.Provisioned.PauseKind } var keep []string if prev != "" { keep = append(keep, prev) } if err := p.ReapKeys(ctx, nameSet.IAMUser, keep); err != nil { return nil, "", fmt.Errorf("mail: reap keys for %s: %w", nameSet.IAMUser, err) } keyID, secret, err := p.MintKey(ctx, nameSet.IAMUser) if err != nil { return nil, "", fmt.Errorf("mail: mint key for %s: %w", nameSet.IAMUser, err) } if err := enforceKeyActive(ctx, p, nameSet.IAMUser, keyID, active); err != nil { return nil, "", err } overlayETag, err := writeSMTPEnvInstance(ctx, s, sealPub, acct, app, sn, d.Region, keyID, secret) if err != nil { return nil, "", err } sn.Provisioned = &Provisioned{ IAMUser: nameSet.IAMUser, UserARN: userARN, KeyID: keyID, PrevKeyID: prev, Active: active, PauseKind: pauseKind, At: now, } if _, err := PutSender(ctx, s, acct, app, sn, etag); err != nil { return nil, "", err } return sn, overlayETag, nil } ``` - [ ] **Step 4: Run the test — expect success** ```bash GOCACHE=/tmp/claude-1001/gocache GOFLAGS=-mod=mod GOPROXY=off go test ./internal/mail/ -count=1 ``` - [ ] **Step 5: Gate and commit** ```bash gofmt -w internal/mail/instance.go internal/mail/instance_test.go GOCACHE=/tmp/claude-1001/gocache GOFLAGS=-mod=mod GOPROXY=off go build ./... && \ GOCACHE=/tmp/claude-1001/gocache GOFLAGS=-mod=mod GOPROXY=off go vet ./... && \ GOCACHE=/tmp/claude-1001/gocache GOFLAGS=-mod=mod GOPROXY=off go test ./... -count=1 && \ gofmt -l . git commit -am "mail: enable an instance sender into its own config layer (plan 5, task 5) Co-Authored-By: Claude Opus 5 " ``` --- ### Task 6: Rotating and tearing down one instance sender **Files:** - Modify: `internal/mail/instance.go`, `internal/mail/instance_test.go` **Interfaces:** - Consumes: plan 4's `appconfig.DeleteInstanceConfig(ctx, s, acct, app, host) error`; plan 2's `DeleteCallerIndex`, `DisassociateTenantResource`; task 3's `TeardownSender`; `Rotate`/`RotateFinish` (`walk.go:864`, `:918`) as the shape; `ErrNotProvisioned`. - Produces: ```go func RotateInstance(ctx context.Context, s release.Store, p Provisioner, sealPub *ecdh.PublicKey, d Deployment, acct, app, sender string, now time.Time) (*Sender, string, error) func RotateFinishInstance(ctx context.Context, s release.Store, p Provisioner, acct, app, sender string) (*Sender, error) func TeardownInstance(ctx context.Context, s release.Store, p Provisioner, w dnsrec.Writer, d Deployment, acct, app, sender string) error ``` - [ ] **Step 1: Write the failing test** `internal/mail/instance_test.go` (append): ```go // A rotation keeps the previous key live until it is finished, exactly as // the app-level one does, and the new key reaches the instance layer alone. func TestRotateInstanceOverlapsThenFinishes(t *testing.T) { ctx, s, p, pub, now := instanceEnableFixture(t) first, _, err := EnableInstance(ctx, s, p, pub, testDeployment(), "bag", "harbourmail", "book.example.com", now) if err != nil { t.Fatal(err) } rotated, etag, err := RotateInstance(ctx, s, p, pub, testDeployment(), "bag", "harbourmail", "book.example.com", now) if err != nil { t.Fatal(err) } if rotated.Provisioned.KeyID == first.Provisioned.KeyID { t.Fatal("the rotation did not mint a new key") } if rotated.Provisioned.PrevKeyID != first.Provisioned.KeyID { t.Fatalf("PrevKeyID = %q, want the key that was live %q", rotated.Provisioned.PrevKeyID, first.Provisioned.KeyID) } if etag == "" { t.Fatal("the rotation returned no overlay etag") } over, gotEtag, _, err := appconfig.LoadInstanceConfig(ctx, s, "bag", "harbourmail", "book.example.com") if err != nil { t.Fatal(err) } _, _, user, _, _ := EnvNames("HARBOURMAIL_SMTP") if gotEtag != etag || over.Vars[user].Value != rotated.Provisioned.KeyID { t.Fatalf("the rotated key did not reach the overlay: etag %q vs %q, user %q", gotEtag, etag, over.Vars[user].Value) } done, err := RotateFinishInstance(ctx, s, p, "bag", "harbourmail", "book.example.com") if err != nil { t.Fatal(err) } if done.Provisioned.PrevKeyID != "" { t.Fatalf("PrevKeyID survived the finish: %q", done.Provisioned.PrevKeyID) } if keys := p.Keys(done.Provisioned.IAMUser); len(keys) != 1 || keys[0] != done.Provisioned.KeyID { t.Fatalf("keys after finish = %q, want only the current one", keys) } } // Teardown removes the principal, the overlay, the caller index and this // sender's references on every domain, and leaves a sibling instance's // domain and credential untouched. func TestTeardownInstanceLeavesASiblingAlone(t *testing.T) { ctx, s, p, pub, now := instanceEnableFixture(t) if _, _, err := EnableInstance(ctx, s, p, pub, testDeployment(), "bag", "harbourmail", "book.example.com", now); err != nil { t.Fatal(err) } sibling := declareAndEnableInstance(t, ctx, s, p, pub, now, "shop.example.com") if err := TeardownInstance(ctx, s, p, dnsrec.NewMemWriter(), testDeployment(), "bag", "harbourmail", "book.example.com"); err != nil { t.Fatal(err) } if _, _, found, err := appconfig.LoadInstanceConfig(ctx, s, "bag", "harbourmail", "book.example.com"); err != nil || found { t.Fatalf("the torn-down instance's overlay survived: %v %v", found, err) } gone, _, err := GetSender(ctx, s, "bag", "harbourmail", "book.example.com") if err != nil || gone != nil { t.Fatalf("the sender object survived its teardown: %+v %v", gone, err) } // The sibling is untouched: its sender, its overlay and its domain. still, _, err := GetSender(ctx, s, "bag", "harbourmail", "shop.example.com") if err != nil || still == nil || still.Provisioned.KeyID != sibling.Provisioned.KeyID { t.Fatalf("the sibling sender moved: %+v %v", still, err) } if _, _, found, err := appconfig.LoadInstanceConfig(ctx, s, "bag", "harbourmail", "shop.example.com"); err != nil || !found { t.Fatalf("the sibling's overlay was removed: %v %v", found, err) } if keys := p.Keys(still.Provisioned.IAMUser); len(keys) == 0 { t.Fatal("the sibling's credential was reaped by another instance's teardown") } } ``` `declareAndEnableInstance` is a helper beside the fixture: declare a second instance sender, attach and verify its own domain through `EnsureDomainForSender`/`VerifyDomain`, enable it, return the sender. - [ ] **Step 2: Run the test — expect failure** ```bash GOCACHE=/tmp/claude-1001/gocache GOFLAGS=-mod=mod GOPROXY=off go test ./internal/mail/ -run 'RotateInstance|TeardownInstance' -count=1 ``` Expected: build failure, `undefined: RotateInstance`, `undefined: RotateFinishInstance`, `undefined: TeardownInstance`. - [ ] **Step 3: Implement** `internal/mail/instance.go`, append. `RotateInstance` is `Rotate`'s body with three substitutions and nothing else: the sender is read with `GetSender`, the principal name comes from `senderNamesOf`, and delivery goes through `writeSMTPEnvInstance` so the overlay etag comes back. Keep `Rotate`'s two rules verbatim, with their comments: the previous key is KEPT (`ReapKeys(user, keep)` with the current id, so the overlap is deliberate and finishable), and `enforceKeyActive` is applied to the fresh key so a rotation cannot lift a pause. `RotateFinishInstance` is `RotateFinish`'s body with the same substitutions, and it deletes the previous key and clears `PrevKeyID`. ```go // TeardownInstance dismantles one instance sender: its principal, its // caller index, its tenant associations, its claims and domain references, // its config overlay and its record. // // THE OVERLAY GOES FIRST, before TeardownSender destroys the principal. // The order matters on a crash: an overlay left standing beside a deleted // IAM user is a live instance failing SMTP auth with nothing to point at, // whereas an overlay removed ahead of a principal that survives is an // instance with no credential and an IAM user a re-run reaps. The second is // repairable by running this again; the first is not repairable at all // without a re-enable nobody knows to ask for. // // Leaving per-instance mode is NOT done here. This function does not know // whether it removed the last instance sender, and finding out is a prefix // listing that races another instance's enable. The DELETE door decides it, // after this returns (design §6.3). func TeardownInstance(ctx context.Context, s release.Store, p Provisioner, w dnsrec.Writer, d Deployment, acct, app, sender string) error { sn, _, err := GetSender(ctx, s, acct, app, sender) if err != nil { return err } if sn == nil { return nil // already gone: idempotent, like every teardown here } if sn.Scope != ScopeInstance { return ErrNotInstanceSender } if err := appconfig.DeleteInstanceConfig(ctx, s, acct, app, sn.Host); err != nil { return err } return TeardownSender(ctx, s, p, w, d, acct, app, sender) } ``` **`TeardownSender` is where the caller index and the tenant associations are undone**, because plan 2 put both in `Teardown`'s body and task 3 renamed it. Check while implementing this task that the renamed function still calls `DeleteCallerIndex` for the sender it is tearing down, and still disassociates before `DeleteIdentity`. If plan 2 wired either to the app sender's names specifically, widen it to `senderNamesOf`. - [ ] **Step 4: Run the test — expect success** ```bash GOCACHE=/tmp/claude-1001/gocache GOFLAGS=-mod=mod GOPROXY=off go test ./internal/mail/ -count=1 ``` - [ ] **Step 5: Gate and commit** ```bash gofmt -w internal/mail/instance.go internal/mail/instance_test.go GOCACHE=/tmp/claude-1001/gocache GOFLAGS=-mod=mod GOPROXY=off go build ./... && \ GOCACHE=/tmp/claude-1001/gocache GOFLAGS=-mod=mod GOPROXY=off go vet ./... && \ GOCACHE=/tmp/claude-1001/gocache GOFLAGS=-mod=mod GOPROXY=off go test ./... -count=1 && \ gofmt -l . git commit -am "mail: rotate and tear down one instance sender (plan 5, task 6) Co-Authored-By: Claude Opus 5 " ``` --- ### Task 7: The box says which uid it renders and which config schema it understands **Files:** - Modify: `internal/status/snapshot.go` (`Probes`, `BoxMetrics`, `CollectBox`), `internal/host/metrics_loop.go` (`routeUIDShape`), `internal/host/agent.go` (the status tick's `status.Probes` literal), `internal/status/snapshot_test.go`, `internal/host/metrics_loop_test.go` **Interfaces:** - Consumes: `registry.Route.{Backing,Unit,Kind,App,Platform,Caps}` (`internal/registry/registry.go`), `registry.BackingUnit` (`:294`), `caps.ParseGrants(col string) (Grants, error)` (`internal/caps/grants.go:92`), `caps.Grants.HostRole`, `appconfig.ConfigAckSchema` (plan 4), `release.Adoptable` (`internal/release/adopt.go:816`). - Produces: ```go // internal/status const ( UIDDynamic = "dynamic" // DynamicUser=yes: a fresh uid per start, shared with nobody UIDApp = "app" // User=carlos-: one uid per app, shared by every instance of it UIDAgent = "agent" // an exec child of the agent: the agent's own uid, shared by everything ) // Probes gains: ConfigSchema int; RouteUIDs map[string]string // BoxMetrics gains: ConfigSchema int `json:"config_schema,omitempty"`; RouteUIDs map[string]string `json:"route_uids,omitempty"` // internal/host func routeUIDShape(rt registry.Route) string ``` **Why this lives on the box and not in the console.** Both facts the enable refusals need are box-local. `registry.Route.Backing` and the operator's `caps` grant column live in a box's own SQLite registry, and a console reads only the registry of the machine it runs on (`internal/console/view.go`'s `openRegistry` over `s.cfg.Registry`), so it cannot answer either question for an instance on any other box — and titogo's customers are not all on the console's box. `status/boxes/