hub: review fix 4 — the hub writes the household's receipt; a box cannot word it or flood it (D84)

offsite_end_scheduled bypasses the household's switches and went through the
ordinary customer leg: subject and body were the box's own sentence, and 50
invented subjects gave 50 mails.

- processReceipt: the details must name a checked app (app-name shape, not
  reserved) and two parsed dates; the mail is rendered only from the hub's
  bundle with that app and the parsed end date — never the box's message.
- The cooldown key is the checked app + the parsed time of the press.
- At most 5 receipts per household in 24 hours, counted in the hub's sent log;
  drops are said once a day; old receipt keys leave the cooldown map.
- Pinned: a blocked household and a household with no address get none.

Tests seen red before the fix; 12 mutations seen red, 3 after a redo
(documentation/audits/build-release-4-2026-11-15/A/redproof-review-4.txt).

Claude-Session: https://claude.ai/code/session_0159rPz1ZhFKsS53msqPYxtS
This commit is contained in:
admin committed 2026-11-15 14:46:27 +01:00
1 parent 875c339cf5
commit be272b7cf4
10 files changed
+455 -26

No files matched your search

@@ -0,0 +1,170 @@
package notify
import (
"fmt"
"strings"
"testing"
"time"
)
// Review of 2026-11-15, finding 4: `offsite_end_scheduled` let a box mail its household without limit and with its
// own words — 50 subjects gave 50 mails, and the subject and body were the box's sentence. A receipt is now built by
// the HUB alone, from a checked app name and parsed dates; a household gets at most receiptsPerDay of them a day.
// RED-PROOF: documentation/audits/build-release-4-2026-11-15/A/redproof-review-4.txt.
func receiptDet(app string, removed time.Time) string {
return fmt.Sprintf(`{"stack_name":%q,"removed_at":%q,"ends_at":%q,"subject":"whatever the box says"}`,
app, removed.UTC().Format(time.RFC3339), removed.Add(30*24*time.Hour).UTC().Format(time.RFC3339))
}
// A box that posts free words under many subjects: no mail carries its words, and the household gets at most the
// daily limit — whatever the subjects, the app names or the times it invents.
func TestD84_Receipt_ABoxCannotFloodOrWordTheHouseholdsMail(t *testing.T) {
d, mails := receiptDispatcher(t, "customer@example.com", []string{})
evil := "ANY WORDS THE BOX CHOOSES: pay at http://evil.example"
now := time.Now().UTC()
// 50 subjects with no app at all (the review's reproduction): not one mail
for i := 0; i < 50; i++ {
d.ProcessBoxEvent("c1", "offsite_end_scheduled", "info", evil, evil, fmt.Sprintf(`{"subject":"x%d"}`, i), "controller")
}
if len(*mails) != 0 {
t.Fatalf("%d mail(s) for receipts that name no app; subject=%q", len(*mails), (*mails)[0].subject)
}
// 50 valid-looking presses, each another app and another time, each with the box's own words
for i := 0; i < 50; i++ {
d.ProcessBoxEvent("c1", "offsite_end_scheduled", "info", evil, evil, receiptDet(fmt.Sprintf("app-%d", i), now.Add(-time.Duration(i)*time.Minute)), "controller")
}
if len(*mails) != receiptsPerDay {
t.Fatalf("50 presses in one burst gave %d mails, want the daily limit %d", len(*mails), receiptsPerDay)
}
for _, m := range *mails {
if strings.Contains(m.subject, "evil") || strings.Contains(m.body, "evil") || strings.Contains(m.body, "ANY WORDS") {
t.Fatalf("the box's own words reached the household:\n%s\n%s", m.subject, m.body)
}
if !strings.Contains(m.subject, "a távoli másolatok törlésre kijelölve") || !strings.Contains(m.body, "Mégis megtartom") {
t.Fatalf("not the hub's own receipt:\n%s\n%s", m.subject, m.body)
}
}
// the cooldown map did not grow with the box's inventions
d.mu.Lock()
n := 0
for k := range d.custCooldowns {
if strings.HasPrefix(k, "c1:offsite_end_scheduled") {
n++
}
}
d.mu.Unlock()
if n > receiptsPerDay {
t.Fatalf("the cooldown map holds %d receipt keys for one household, want at most %d", n, receiptsPerDay)
}
}
// What the mail says comes from the details the hub CHECKED: the app name's shape, the dates as times.
func TestD84_Receipt_IsBuiltFromCheckedDetailsOnly(t *testing.T) {
now := time.Now().UTC()
good := func(app string) string { return receiptDet(app, now) }
for name, det := range map[string]string{
"no stack_name": `{"removed_at":"2026-11-15T10:00:00Z","ends_at":"2026-12-15T10:00:00Z"}`,
"a sentence as the app name": strings.Replace(good("x"), `"x"`, `"pay now at evil.example"`, 1),
"markup as the app name": strings.Replace(good("x"), `"x"`, `"<b>x</b>"`, 1),
"a reserved name": good("traefik"),
"the shares": good("_shares"),
"removed_at is not a time": `{"stack_name":"vikunja","removed_at":"yesterday","ends_at":"2026-12-15T10:00:00Z"}`,
"ends_at is not a time": `{"stack_name":"vikunja","removed_at":"2026-11-15T10:00:00Z","ends_at":"soon; click evil.example"}`,
"ends before it was removed": `{"stack_name":"vikunja","removed_at":"2026-11-15T10:00:00Z","ends_at":"2026-11-01T10:00:00Z"}`,
"details are not JSON": `not json`,
"no details": ``,
} {
d, mails := receiptDispatcher(t, "customer@example.com", nil)
d.ProcessBoxEvent("c1", "offsite_end_scheduled", "info", "box words", "box words", det, "controller")
if len(*mails) != 0 {
t.Errorf("%s: a mail went out: %q", name, (*mails)[0].subject)
}
}
// the date in the mail is the PARSED ends_at, in the household's date form — not text from the box
d, mails := receiptDispatcher(t, "customer@example.com", nil)
d.ProcessBoxEvent("c1", "offsite_end_scheduled", "info", "Törlésük napja: 1999. 01. 01.", "",
`{"stack_name":"vikunja","removed_at":"2026-11-15T10:00:00Z","ends_at":"2026-12-15T10:00:00Z"}`, "controller")
if len(*mails) != 1 || !strings.Contains((*mails)[0].body, "2026. 12. 15.") || strings.Contains((*mails)[0].body, "1999") {
t.Fatalf("the mail must carry the parsed end date and none of the box's text: %+v", *mails)
}
// the press's key is the checked app + the parsed time: the same press again, with another `subject` and the time
// written in another zone, is NOT a second mail
d.ProcessBoxEvent("c1", "offsite_end_scheduled", "info", "x", "",
`{"stack_name":"vikunja","removed_at":"2026-11-15T11:00:00+01:00","ends_at":"2026-12-15T10:00:00Z","subject":"another"}`, "controller")
if len(*mails) != 1 {
t.Fatalf("one press sent twice with a changed subject gave %d mails", len(*mails))
}
}
// A blocked household gets no receipt.
func TestD84_Receipt_ABlockedHouseholdGetsNone(t *testing.T) {
d, mails := receiptDispatcher(t, "customer@example.com", nil)
if err := d.store.SetCustomerConfigStatus("c1", "blocked"); err != nil {
t.Fatal(err)
}
d.ProcessBoxEvent("c1", "offsite_end_scheduled", "info", "x", "", receiptDet("vikunja", time.Now()), "controller")
if len(*mails) != 0 {
t.Fatalf("a blocked household was mailed: %+v", *mails)
}
if err := d.store.SetCustomerConfigStatus("c1", "active"); err != nil {
t.Fatal(err)
}
d.ProcessBoxEvent("c1", "offsite_end_scheduled", "info", "x", "", receiptDet("vikunja", time.Now()), "controller")
if len(*mails) != 1 {
t.Fatalf("positive control: an unblocked household must get the receipt, got %d", len(*mails))
}
}
// The map of mailed presses does not grow for ever: a household's receipt keys older than a day go at its next
// receipt; another household's keys and other event types' keys are not touched.
func TestD84_Receipt_OldPressesLeaveTheCooldownMap(t *testing.T) {
d, mails := receiptDispatcher(t, "customer@example.com", nil)
old := time.Now().Add(-25 * time.Hour)
d.mu.Lock()
for i := 0; i < 30; i++ {
d.custCooldowns[fmt.Sprintf("c1:offsite_end_scheduled:old-%d|x", i)] = old
}
d.custCooldowns["c2:offsite_end_scheduled:other|x"] = old
d.custCooldowns["c1:app_update_undone:vikunja"] = old
d.mu.Unlock()
d.ProcessBoxEvent("c1", "offsite_end_scheduled", "info", "x", "", receiptDet("vikunja", time.Now()), "controller")
if len(*mails) != 1 {
t.Fatalf("30 presses of yesterday must not count against today's limit: %d mail(s)", len(*mails))
}
d.mu.Lock()
defer d.mu.Unlock()
n := 0
for k := range d.custCooldowns {
if strings.HasPrefix(k, "c1:offsite_end_scheduled:") {
n++
}
}
if n != 1 {
t.Fatalf("the household's receipt keys: %d, want only today's one", n)
}
if _, ok := d.custCooldowns["c2:offsite_end_scheduled:other|x"]; !ok {
t.Fatal("another household's key was removed")
}
if _, ok := d.custCooldowns["c1:app_update_undone:vikunja"]; !ok {
t.Fatal("another event type's key was removed")
}
}
// The daily limit is the hub's own SENT LOG, so a hub restart (an empty map) does not give a box five more.
func TestD84_Receipt_TheDailyLimitSurvivesARestart(t *testing.T) {
d, mails := receiptDispatcher(t, "customer@example.com", nil)
for i := 0; i < receiptsPerDay; i++ {
d.ProcessBoxEvent("c1", "offsite_end_scheduled", "info", "x", "", receiptDet(fmt.Sprintf("app-%d", i), time.Now()), "controller")
}
if len(*mails) != receiptsPerDay {
t.Fatalf("fixture: %d mails", len(*mails))
}
d.mu.Lock()
d.custCooldowns = map[string]time.Time{} // the restart
d.mu.Unlock()
d.ProcessBoxEvent("c1", "offsite_end_scheduled", "info", "x", "", receiptDet("one-more", time.Now()), "controller")
if len(*mails) != receiptsPerDay {
t.Fatalf("after a restart the household got mail number %d of the day (limit %d)", len(*mails), receiptsPerDay)
}
}
+1 -1
View File
@@ -83,7 +83,7 @@ func TestD84_Receipt_FollowsTheHouseholdsLanguage(t *testing.T) {
func TestD84_Receipt_OncePerPress(t *testing.T) {
d, mails := receiptDispatcher(t, "customer@example.com", nil)
send := func(app, removedAt string) {
det := `{"stack_name":"` + app + `","removed_at":"` + removedAt + `","subject":"` + app + `|` + removedAt + `"}`
det := `{"stack_name":"` + app + `","removed_at":"` + removedAt + `","ends_at":"2026-12-15T10:00:00Z","subject":"` + app + `|` + removedAt + `"}`
d.ProcessBoxEvent("c1", "offsite_end_scheduled", "info", "x "+app, "", det, "controller")
}
send("vikunja", "2026-11-15T10:00:00Z")
+148 -21
View File
@@ -32,6 +32,8 @@ type Dispatcher struct {
mu sync.Mutex
opCooldowns map[string]time.Time // "customerID:eventType" → last operator notify
custCooldowns map[string]time.Time // "customerID:eventType" → last customer notify
// receiptDropDay: per household, the UTC day on which a dropped receipt was last said in the log (once a day).
receiptDropDay map[string]string
// sendEmailFn is the email sender, seam-injected so tests exercise routing without real HTTP.
// Defaults to (*Dispatcher).sendEmail (Resend) in NewDispatcher. headers (nil = none) become
@@ -248,7 +250,7 @@ func (d *Dispatcher) processEvent(customerID, eventType, severity, message, mess
// Before the severity gate (the event is `info`: nothing is wrong) and with no operator mail: the event row is
// the operator's record.
if householdReceiptEvents[eventType] {
d.processCustomer(customerID, eventType, severity, message, messageCustomer, detailsJSON, source)
d.processReceipt(customerID, eventType, severity, detailsJSON)
return
}
@@ -777,31 +779,158 @@ var recordOnlyEvents = map[string]bool{
// deleted and how to take it back. The reviewer's reason, accepted by the operator: the page alone does not warn a
// household whose login someone else uses.
//
// THREE THINGS FOLLOW FROM THAT REASON, each pinned by TestD84_Receipt*:
// - it goes to the household's own notification address by the customer leg (processCustomer) — no second path;
// - it does NOT read the household's group switches (`enabled_events`): whoever holds the login could switch a
// group off first, and this is not a detector the household tunes — it is a receipt;
// - its cooldown is per PRESS (details `subject` = app + the record's own time), so two apps removed in one hour
// are two mails, and one press delivered twice is one mail.
// A receipt bypasses the household's group switches (whoever holds the login could switch a group off first) — so it
// is the one household mail a BOX can cause whatever the household chose, and it is built so a box can do nothing
// else with it (review of 2026-11-15; processReceipt):
// - THE HUB WRITES IT. Subject and body come only from the hub's own bundle, with an app name the hub checked
// (the shape of an app name, not reserved) and dates the hub parsed. The box's `message` is never mailed.
// - ONE PER PRESS. The cooldown key is the checked app + the parsed time of the press — not the box's free
// `subject` — so one press delivered twice is one mail, and two apps removed in one hour are two.
// - AT MOST receiptsPerDay PER HOUSEHOLD IN 24 HOURS, counted in the hub's own sent log (it survives a restart).
// The rest are dropped; the hub says so once a day per household.
// - to the household's own notification address by the customer leg's own delivery; never to the operator.
//
// A household with NO address gets no mail — the page is all it has (`07` §8.2f). A blocked household gets none.
// The operator is not mailed: the event row is the record.
// Pinned by TestD84_Receipt*.
var householdReceiptEvents = map[string]bool{
"offsite_end_scheduled": true,
}
// receiptSubjectSuffix returns ":"+subject for a receipt whose details carry a non-empty `subject`.
func receiptSubjectSuffix(eventType, detailsJSON string) string {
if !householdReceiptEvents[eventType] {
return ""
}
// receiptsPerDay is the most receipts ONE household is mailed in 24 hours (review of 2026-11-15).
const receiptsPerDay = 5
// receiptCooldown: the same press is never mailed twice within this time.
const receiptCooldown = 24 * time.Hour
// receipt is what the hub accepts of a receipt's details.
type receipt struct {
App string
Removed time.Time
Ends time.Time
}
// parseReceipt checks a receipt's details. ok=false → nothing is mailed. The app must have the shape of an app name
// and not be reserved (store.ValidPresenceApp / ReservedPresenceApp — the same check the hub's app record uses); the
// two dates must be times, and the end must be after the press and at most 40 days after it.
func parseReceipt(detailsJSON string) (receipt, bool) {
var d struct {
Subject string `json:"subject"`
StackName string `json:"stack_name"`
RemovedAt string `json:"removed_at"`
EndsAt string `json:"ends_at"`
}
if err := json.Unmarshal([]byte(detailsJSON), &d); err != nil || d.Subject == "" {
return ""
if detailsJSON == "" || json.Unmarshal([]byte(detailsJSON), &d) != nil {
return receipt{}, false
}
return ":" + d.Subject
if !store.ValidPresenceApp(d.StackName) || store.ReservedPresenceApp(d.StackName) {
return receipt{}, false
}
removed, err1 := time.Parse(time.RFC3339, d.RemovedAt)
ends, err2 := time.Parse(time.RFC3339, d.EndsAt)
if err1 != nil || err2 != nil || !ends.After(removed) || ends.Sub(removed) > 40*24*time.Hour {
return receipt{}, false
}
return receipt{App: d.StackName, Removed: removed.UTC(), Ends: ends.UTC()}, true
}
// receiptDate writes a day in the household's date form (the controller's i18n.FormatDate), in Budapest time.
func receiptDate(lang string, t time.Time) string {
if budapest != nil {
t = t.In(budapest)
}
if i18n.Normalize(lang) == "en" {
return t.Format("2006-01-02")
}
return t.Format("2006. 01. 02.")
}
// FormatReceiptEmail is the receipt's whole text — the hub's own words and the checked details, nothing of the box's.
func FormatReceiptEmail(lang, customerID, eventType, severity string, rc receipt) (string, string) {
b := i18n.Shared()
lang = i18n.Normalize(lang)
sentence := b.Msgf(lang, "mail.receipt."+eventType, rc.App, receiptDate(lang, rc.Ends))
// The details the frame reads (the app for the headline) are rebuilt from the CHECKED values.
det, _ := json.Marshal(map[string]string{"stack_name": rc.App})
return FormatCustomerEmail(lang, customerID, eventType, severity, sentence, "", string(det))
}
// processReceipt mails ONE receipt to the household, or drops it — see householdReceiptEvents.
func (d *Dispatcher) processReceipt(customerID, eventType, severity, detailsJSON string) {
rc, ok := parseReceipt(detailsJSON)
if !ok {
d.receiptDropped(customerID, eventType, "its details do not name an app and two dates the hub accepts")
return
}
if d.store.IsCustomerBlocked(customerID) {
return
}
prefs, err := d.store.GetNotificationPrefs(customerID)
if err != nil || prefs == nil || prefs.Email == "" {
return // no address: the page is all the household has
}
key := customerID + ":" + eventType + ":" + rc.App + "|" + rc.Removed.Format(time.RFC3339)
now := time.Now()
sentToday, cerr := d.store.CountCustomerSentSince(customerID, eventType, now.Add(-24*time.Hour))
if cerr != nil {
sentToday = receiptsPerDay // a log that cannot be read is not „nothing sent”: no receipt goes
}
d.mu.Lock()
// The map holds only presses of the last day: older keys of this household's receipts go now.
prefix, inFlight := customerID+":"+eventType+":", 0
for k, at := range d.custCooldowns {
if strings.HasPrefix(k, prefix) {
if now.Sub(at) >= receiptCooldown {
delete(d.custCooldowns, k)
} else {
inFlight++
}
}
}
if _, dup := d.custCooldowns[key]; dup {
d.mu.Unlock()
d.logger.Printf("[INFO] Receipt %s for %s/%s skipped — this press was mailed already", eventType, customerID, rc.App)
return
}
// The limit counts what the log says was sent AND what is reserved in memory (a burst is processed faster than
// the log is written).
if sentToday >= receiptsPerDay || inFlight >= receiptsPerDay {
d.mu.Unlock()
d.receiptDropped(customerID, eventType, fmt.Sprintf("the household already got %d receipt(s) in the last 24 hours (the limit)", receiptsPerDay))
return
}
d.custCooldowns[key] = now
d.mu.Unlock()
subject, body := FormatReceiptEmail(d.store.CustomerLanguage(customerID), customerID, eventType, severity, rc)
logMsg := eventType + " " + rc.App
if err := d.deliver("customer receipt "+eventType, customerID, prefs.Email, subject, body, priorityHeaders(severity)); isHeld(err) {
d.forgetCustomerCooldown(key)
d.store.LogNotification(customerID, eventType, severity, logMsg, "held", "MAIL-HOLD marker present — dropped", "customer")
return
} else if err != nil {
d.logger.Printf("[ERROR] Receipt %s failed for %s: %v", eventType, customerID, err)
d.store.LogNotification(customerID, eventType, severity, logMsg, "failed", err.Error(), "customer")
return
}
d.logger.Printf("[INFO] Receipt %s sent for %s/%s", eventType, customerID, rc.App) // never the address (R-922)
d.store.LogNotification(customerID, eventType, severity, logMsg, "sent", "", "customer")
}
// receiptDropped says ONCE per household and day that receipts are being dropped, and why — in the hub's log and as
// one `skipped` row. A box that posts a thousand of them gets one line, not a thousand.
func (d *Dispatcher) receiptDropped(customerID, eventType, why string) {
day := time.Now().UTC().Format("2006-01-02")
d.mu.Lock()
if d.receiptDropDay == nil {
d.receiptDropDay = map[string]string{}
}
already := d.receiptDropDay[customerID] == day
d.receiptDropDay[customerID] = day
d.mu.Unlock()
if already {
return
}
d.logger.Printf("[WARN] Receipt %s from the box of %s was NOT mailed: %s. Further drops for this household are not logged today.", eventType, customerID, why)
d.store.LogNotification(customerID, eventType, "info", eventType, "skipped", "receipt dropped: "+why, "customer")
}
// operatorOnlyEvents are event types that must NEVER reach a customer, whatever their preferences say.
@@ -1146,9 +1275,8 @@ func (d *Dispatcher) processCustomer(customerID, eventType, severity, message, m
return
}
// Check if event type is enabled. A receipt (D84) is not a detector the household switches: see
// householdReceiptEvents.
if !householdReceiptEvents[eventType] && !isEventEnabled(prefs.EnabledEvents, eventType) {
// Check if event type is enabled
if !isEventEnabled(prefs.EnabledEvents, eventType) {
return
}
@@ -1179,7 +1307,6 @@ func (d *Dispatcher) processCustomer(customerID, eventType, severity, message, m
if perAppCustomerCooldownEvents[eventType] {
cooldownKey += cooldownStackSuffixFor(detailsJSON)
}
cooldownKey += receiptSubjectSuffix(eventType, detailsJSON) // D84: one mail per press
d.mu.Lock()
if last, ok := d.custCooldowns[cooldownKey]; ok && time.Since(last) < cooldownDur {
d.mu.Unlock()
+1 -2
View File
@@ -224,8 +224,7 @@ func FormatCustomerEmail(lang, customerID, eventType, severity, message, message
// operator's mail (FormatOperatorEmail) keeps the note. Pinned by r79_health_mail_test.go.
body += b.Msg(lang, "mail.customer.line.health_dashboard")
} else if householdReceiptEvents[eventType] {
// D84: a receipt's details are the record's own fields (app, dates, the press's key) — the sentence above
// already says them in words; the raw JSON would add nothing a household can read.
// D84: a receipt carries no raw details — the hub's own sentence says them in words (FormatReceiptEmail).
} else if detailsJSON != "" && detailsJSON != "{}" {
body += b.Msgf(lang, "mail.customer.line.note", detailsJSON)
}