diff --git a/documentation/architecture/07-backup-architecture.md b/documentation/architecture/07-backup-architecture.md index 76bbccd9..6a5f6db4 100644 --- a/documentation/architecture/07-backup-architecture.md +++ b/documentation/architecture/07-backup-architecture.md @@ -1892,7 +1892,10 @@ part alone, exactly as before, and still raises `offsite_snapshots_vanished`. **The mail (D84)** `[FACT — built, not released]`. At the press the box sends `offsite_end_scheduled`; the hub mails it to the household's own notification address — once per press, in the household's language, whatever its group -switches say (a receipt: `notify.householdReceiptEvents`), and not to the operator. **A household with no +switches say (a receipt: `notify.householdReceiptEvents`), and not to the operator. **The hub writes the mail, not the +box** (review of 2026-11-15): subject and body come from the hub's own bundle, with an app name the hub checked and +the end date it parsed from the details; the box's sentence is never mailed. A household gets at most 5 receipts in +24 hours (counted in the hub's sent log); the rest are dropped and said once a day in the hub's log. **A household with no notification address gets no mail: the page is all it has.** A blocked household gets none either. **Edge cases, each with its rule and its test.** @@ -1985,7 +1988,7 @@ final dot (`2026. 12. 15.`), so the Hungarian sentences have no dot after it. | A press that is refused (the app is installed; no hub tier) | „Ennek az alkalmazásnak a távoli másolatait most nem lehet törlésre kijelölni.” | "The off-site copies of this app cannot be marked for deletion now." | | A record that could not be saved | „Nem sikerült elmenteni. Próbáld újra.” | "This could not be saved. Try again." | | **The mail — subject** | „[Felhom] Információ: {app}: a távoli másolatok törlésre kijelölve” | "[Felhom] Information: {app}: the off-site copies are marked for deletion" | -| **The mail — body** (inside the hub's ordinary household mail frame: greeting, server, time, level, type, sign-off) | „{app}: az alkalmazás távoli másolatai törlésre vannak kijelölve. Törlésük napja: {dátum} Addig a Mentések oldalon a „Mégis megtartom” gombbal visszavonhatod.” | "{app}: the off-site copies of this app are marked for deletion. They are deleted on: {date}. Until then you can take this back on the Backups page with the “Keep it after all” button." | +| **The mail — body** (the HUB's own sentence, `mail.receipt.offsite_end_scheduled`, inside the hub's ordinary household mail frame: greeting, server, time, level, type, sign-off; the box's event carries the same sentence for the event list only) | „{app}: az alkalmazás távoli másolatai törlésre vannak kijelölve. Törlésük napja: {dátum} Addig a Mentések oldalon a „Mégis megtartom” gombbal visszavonhatod.” | "{app}: the off-site copies of this app are marked for deletion. They are deleted on: {date}. Until then you can take this back on the Backups page with the “Keep it after all” button." | No mail to the household at the deletion: it can do nothing with it (`08` §8.1). The operator's records are `offsite_ended_app_removed` (info, per app, not mailed) and `offsite_ended_app_refused` (warning) — `08` §6.5. diff --git a/documentation/audits/build-release-4-2026-11-15/A/redproof-review-4.txt b/documentation/audits/build-release-4-2026-11-15/A/redproof-review-4.txt new file mode 100644 index 00000000..0112e0ee --- /dev/null +++ b/documentation/audits/build-release-4-2026-11-15/A/redproof-review-4.txt @@ -0,0 +1,105 @@ +FINDING 4 — offsite_end_scheduled let a box mail its household without limit and with its own words. + +### RED: the new tests on the hub code before the fix (felhom.eu 875c339c) +=== RUN TestD84_Receipt_ABoxCannotFloodOrWordTheHouseholdsMail + d84_receipt_bounds_test.go:31: 50 mail(s) for receipts that name no app; subject="[Felhom] Információ: ANY WORDS THE BOX CHOOSES: pay at http://evil.example" +--- FAIL: TestD84_Receipt_ABoxCannotFloodOrWordTheHouseholdsMail (0.06s) +=== RUN TestD84_Receipt_IsBuiltFromCheckedDetailsOnly + d84_receipt_bounds_test.go:81: removed_at is not a time: a mail went out: "[Felhom] Információ: vikunja: a távoli másolatok törlésre kijelölve" + d84_receipt_bounds_test.go:81: ends_at is not a time: a mail went out: "[Felhom] Információ: vikunja: a távoli másolatok törlésre kijelölve" + d84_receipt_bounds_test.go:81: ends before it was removed: a mail went out: "[Felhom] Információ: vikunja: a távoli másolatok törlésre kijelölve" + d84_receipt_bounds_test.go:81: no details: a mail went out: "[Felhom] Információ: box words" + d84_receipt_bounds_test.go:81: a reserved name: a mail went out: "[Felhom] Információ: traefik: a távoli másolatok törlésre kijelölve" + d84_receipt_bounds_test.go:81: the shares: a mail went out: "[Felhom] Információ: _shares: a távoli másolatok törlésre kijelölve" + d84_receipt_bounds_test.go:81: no stack_name: a mail went out: "[Felhom] Információ: box words" + d84_receipt_bounds_test.go:81: details are not JSON: a mail went out: "[Felhom] Információ: box words" + d84_receipt_bounds_test.go:81: a sentence as the app name: a mail went out: "[Felhom] Információ: pay now at evil.example: a távoli másolatok törlésre kijelölve" + d84_receipt_bounds_test.go:81: markup as the app name: a mail went out: "[Felhom] Információ: x: a távoli másolatok törlésre kijelölve" + d84_receipt_bounds_test.go:89: the mail must carry the parsed end date and none of the box's text: [{to:customer@example.com subject:[Felhom] Információ: vikunja: a távoli másolatok törlésre kijelölve body:Kedves Ügyfél! +--- FAIL: TestD84_Receipt_IsBuiltFromCheckedDetailsOnly (0.49s) +=== RUN TestD84_Receipt_ABlockedHouseholdGetsNone +--- PASS: TestD84_Receipt_ABlockedHouseholdGetsNone (0.04s) +FAIL +FAIL gitea.dooplex.hu/admin/felhom-hub/internal/notify 0.613s +FAIL +(TestD84_Receipt_ABlockedHouseholdGetsNone passed before the fix too: the customer leg already skipped a blocked household. It is a pin, and it has its own mutation below.) + +### After the fix: mutations +== MUTATION: the receipt goes through the ordinary customer leg again (the box's words, the box's subject) + RED on the mutant, GREEN on the real file + --- FAIL: TestD84_Receipt_ABoxCannotFloodOrWordTheHouseholdsMail (0.04s) + d84_receipt_bounds_test.go:38: 50 presses in one burst gave 0 mails, want the daily limit 5 + --- FAIL: TestD84_Receipt_IsBuiltFromCheckedDetailsOnly (0.48s) + d84_receipt_bounds_test.go:89: the mail must carry the parsed end date and none of the box's text: [] +== MUTATION: no daily limit + *** NOT A RED-PROOF *** (mutant rc=1 built=False real rc=0) + FAIL gitea.dooplex.hu/admin/felhom-hub/internal/notify [build failed] + internal/notify/dispatcher.go:872:2: declared and not used: sentToday +== MUTATION: the limit trusts the sent log alone (a burst is faster than the log) + *** NOT A RED-PROOF *** (mutant rc=0 built=True real rc=0) +== MUTATION: the app name is not checked + RED on the mutant, GREEN on the real file + --- FAIL: TestD84_Receipt_IsBuiltFromCheckedDetailsOnly (0.40s) + d84_receipt_bounds_test.go:81: a sentence as the app name: a mail went out: "[Felhom] Információ: pay now at evil.example: a távoli másolatok törlésre kijelölve" + d84_receipt_bounds_test.go:81: the shares: a mail went out: "[Felhom] Információ: _shares: a távoli másolatok törlésre kijelölve" + d84_receipt_bounds_test.go:81: markup as the app name: a mail went out: "[Felhom] Információ: x: a távoli másolatok törlésre kijelölve" +== MUTATION: a reserved name gets a receipt + RED on the mutant, GREEN on the real file + --- FAIL: TestD84_Receipt_IsBuiltFromCheckedDetailsOnly (0.44s) + d84_receipt_bounds_test.go:81: a reserved name: a mail went out: "[Felhom] Információ: traefik: a távoli másolatok törlésre kijelölve" +== MUTATION: the dates are not checked + RED on the mutant, GREEN on the real file + --- FAIL: TestD84_Receipt_IsBuiltFromCheckedDetailsOnly (0.46s) + d84_receipt_bounds_test.go:81: removed_at is not a time: a mail went out: "[Felhom] Információ: vikunja: a távoli másolatok törlésre kijelölve" + d84_receipt_bounds_test.go:81: ends_at is not a time: a mail went out: "[Felhom] Információ: vikunja: a távoli másolatok törlésre kijelölve" + d84_receipt_bounds_test.go:81: ends before it was removed: a mail went out: "[Felhom] Információ: vikunja: a távoli másolatok törlésre kijelölve" +== MUTATION: an end before the press is accepted + RED on the mutant, GREEN on the real file + --- FAIL: TestD84_Receipt_IsBuiltFromCheckedDetailsOnly (0.49s) + d84_receipt_bounds_test.go:81: ends before it was removed: a mail went out: "[Felhom] Információ: vikunja: a távoli másolatok törlésre kijelölve" +== MUTATION: the press's key is the app alone + RED on the mutant, GREEN on the real file + --- FAIL: TestD84_Receipt_OncePerPress (0.04s) + d84_receipt_test.go:97: three presses gave 2 mails, want 3: [{to:customer@example.com subject:[Felhom] Információ: vikunja: a távoli másolatok törlésre kijelölve body:Kedves Ügyfél! +== MUTATION: the press's time is keyed as the box wrote it (another zone = another press) + RED on the mutant, GREEN on the real file + --- FAIL: TestD84_Receipt_IsBuiltFromCheckedDetailsOnly (0.47s) + d84_receipt_bounds_test.go:96: one press sent twice with a changed subject gave 2 mails +== MUTATION: a blocked household gets the receipt + RED on the mutant, GREEN on the real file + --- FAIL: TestD84_Receipt_ABlockedHouseholdGetsNone (0.04s) + d84_receipt_bounds_test.go:108: a blocked household was mailed: [{to:customer@example.com subject:[Felhom] Információ: vikunja: a távoli másolatok törlésre kijelölve body:Kedves Ügyfél! +== MUTATION: old presses stay in the cooldown map (and count against today) + *** NOT A RED-PROOF *** (mutant rc=1 built=False real rc=0) + FAIL gitea.dooplex.hu/admin/felhom-hub/internal/notify [build failed] + internal/notify/dispatcher.go:879:9: declared and not used: at +== MUTATION: the mail's date is today, not the parsed end + RED on the mutant, GREEN on the real file + --- FAIL: TestD84_Receipt_IsBuiltFromCheckedDetailsOnly (0.47s) + d84_receipt_bounds_test.go:89: the mail must carry the parsed end date and none of the box's text: [{to:customer@example.com subject:[Felhom] Információ: vikunja: a távoli másolatok törlésre kijelölve body:Kedves Ügyfél! + --- FAIL: TestD84_Receipt_ReachesTheHouseholdWhateverItsSwitches (0.04s) + d84_receipt_test.go:54: the body lacks "2026. 12. 15.": + +12 mutations, 3 not a red-proof + +### the three mutations done again +== MUTATION: REDO (the first mutant did not compile): no daily limit + RED on the mutant, GREEN on the real file + --- FAIL: TestD84_Receipt_ABoxCannotFloodOrWordTheHouseholdsMail (0.07s) + d84_receipt_bounds_test.go:38: 50 presses in one burst gave 50 mails, want the daily limit 5 + --- FAIL: TestD84_Receipt_TheDailyLimitSurvivesARestart (0.04s) + d84_receipt_bounds_test.go:168: after a restart the household got mail number 6 of the day (limit 5) +== MUTATION: REDO (the first mutant was built wrongly: it left the part it meant to remove; and the test that sees this one was added): the limit does not read the sent log (a restart gives five more) + RED on the mutant, GREEN on the real file + --- FAIL: TestD84_Receipt_TheDailyLimitSurvivesARestart (0.05s) + d84_receipt_bounds_test.go:168: after a restart the household got mail number 6 of the day (limit 5) +== MUTATION: REDO (the first mutant did not compile): old presses stay in the cooldown map (and count against today) + RED on the mutant, GREEN on the real file + --- FAIL: TestD84_Receipt_OldPressesLeaveTheCooldownMap (0.04s) + d84_receipt_bounds_test.go:133: 30 presses of yesterday must not count against today's limit: 0 mail(s) + +3 mutations, 0 not a red-proof + +NOT PROVEN, said plainly: the in-memory half of the limit (`inFlight >= receiptsPerDay`). In a test the events are +processed one after another, so the sent log is always written before the next one is judged and the log half +alone holds the limit. The memory half is for a burst processed in parallel; it stays in the code and is not claimed. diff --git a/hub/CHANGELOG.md b/hub/CHANGELOG.md index 4c671ed2..6133677e 100644 --- a/hub/CHANGELOG.md +++ b/hub/CHANGELOG.md @@ -1,5 +1,19 @@ ## Unreleased (after v0.182.0) +- **Review fix 4 (2026-11-15): a box can no longer word or flood the household's receipt.** `offsite_end_scheduled` + bypasses the household's switches, and it went through the ordinary customer leg: the subject and body were the + box's own sentence, and 50 invented subjects gave 50 mails. Now `Dispatcher.processReceipt`: the details must name + an app of the app-name shape that is not reserved and two parsed dates (the end after the press, at most 40 days); + the mail is rendered ONLY from the hub's bundle (new `mail.receipt.offsite_end_scheduled`, both languages) with + that app and the parsed end date — the box's `message` is never mailed; the cooldown key is the checked app + the + parsed time of the press, not the box's `subject`; **at most 5 receipts per household in 24 hours**, counted in the + hub's own sent log (`store.CountCustomerSentSince`, so a restart gives no more); drops are said once a day per + household; a household's receipt keys older than a day leave the cooldown map. A blocked household and a household + with no address get none (pinned). Tests `TestD84_Receipt_ABoxCannotFloodOrWordTheHouseholdsMail`, + `TestD84_Receipt_IsBuiltFromCheckedDetailsOnly` (seen red before the fix), `TestD84_Receipt_ABlockedHouseholdGetsNone`, + `TestD84_Receipt_OldPressesLeaveTheCooldownMap`, `TestD84_Receipt_TheDailyLimitSurvivesARestart`; 12 mutations seen + red, 3 after a redo; the in-memory half of the limit is not provable in a sequential test and is said so + (`…/A/redproof-review-4.txt`). - **Review fix 1 (2026-11-15): a box that lies about its app list can no longer have the whole store agreed in one window with no signal.** The hub's 30-day check rests on what the box reports, so a box could name an app that never existed (or stop listing a living one), wait 30 days, and get every snapshot agreed beside the cap. Now: diff --git a/hub/internal/i18n/locales/en.json b/hub/internal/i18n/locales/en.json index ade0311f..1cd12146 100644 --- a/hub/internal/i18n/locales/en.json +++ b/hub/internal/i18n/locales/en.json @@ -90,6 +90,7 @@ "mail.event.app_update_held": "%s: the app is stopped and needs a restore", "mail.event.app_stopped_unhealthy": "%s: the app was stopped because it kept crashing", "mail.event.offsite_end_scheduled": "%s: the off-site copies are marked for deletion", + "mail.receipt.offsite_end_scheduled": "%s: the off-site copies of this app are marked for deletion. They are deleted on: %s. Until then you can take this back on the Backups page with the “Keep it after all” button.", "mail.event.app_held": "An app is stopped and waits for a person to act", "mail.event.app_hold_cleared": "The app is no longer held", "mail.event.app_held_reminder": "An app is still held", diff --git a/hub/internal/i18n/locales/hu.json b/hub/internal/i18n/locales/hu.json index d68c769d..ee678ccd 100644 --- a/hub/internal/i18n/locales/hu.json +++ b/hub/internal/i18n/locales/hu.json @@ -90,6 +90,7 @@ "mail.event.app_update_held": "%s: az alkalmazás leállítva, visszaállítás szükséges", "mail.event.app_stopped_unhealthy": "%s: az alkalmazást leállítottuk, mert újra és újra összeomlott", "mail.event.offsite_end_scheduled": "%s: a távoli másolatok törlésre kijelölve", + "mail.receipt.offsite_end_scheduled": "%s: az alkalmazás távoli másolatai törlésre vannak kijelölve. Törlésük napja: %s Addig a Mentések oldalon a „Mégis megtartom” gombbal visszavonhatod.", "mail.event.app_held": "Egy alkalmazás le van állítva, és emberi beavatkozásra vár", "mail.event.app_hold_cleared": "Az alkalmazás leállítása megszűnt", "mail.event.app_held_reminder": "Egy alkalmazás még mindig le van állítva", diff --git a/hub/internal/notify/d84_receipt_bounds_test.go b/hub/internal/notify/d84_receipt_bounds_test.go new file mode 100644 index 00000000..37a6d966 --- /dev/null +++ b/hub/internal/notify/d84_receipt_bounds_test.go @@ -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"`, `"x"`, 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) + } +} diff --git a/hub/internal/notify/d84_receipt_test.go b/hub/internal/notify/d84_receipt_test.go index ccd0d6f1..aa388f1f 100644 --- a/hub/internal/notify/d84_receipt_test.go +++ b/hub/internal/notify/d84_receipt_test.go @@ -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") diff --git a/hub/internal/notify/dispatcher.go b/hub/internal/notify/dispatcher.go index 9bdde952..25a4516c 100644 --- a/hub/internal/notify/dispatcher.go +++ b/hub/internal/notify/dispatcher.go @@ -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() diff --git a/hub/internal/notify/templates.go b/hub/internal/notify/templates.go index b3f63dbe..62839f80 100644 --- a/hub/internal/notify/templates.go +++ b/hub/internal/notify/templates.go @@ -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) } diff --git a/hub/internal/store/offsite_ended.go b/hub/internal/store/offsite_ended.go index c25cddbe..d441b67c 100644 --- a/hub/internal/store/offsite_ended.go +++ b/hub/internal/store/offsite_ended.go @@ -405,3 +405,12 @@ func (s *Store) BackdateOffsiteWindowForTest(id int64, by time.Duration) error { _, err := s.db.Exec(`UPDATE offsite_windows SET opened_at = ? WHERE id = ?`, time.Now().UTC().Add(-by).Format("2006-01-02 15:04:05"), id) return err } + +// CountCustomerSentSince counts the mails of one type the hub's own log says were SENT to a household since `since` +// (the receipt's daily limit — it survives a hub restart, which a counter in memory would not). +func (s *Store) CountCustomerSentSince(customerID, eventType string, since time.Time) (int, error) { + var n int + err := s.db.QueryRow(`SELECT COUNT(*) FROM notification_log WHERE customer_id = ? AND event_type = ? AND channel = 'customer' AND status = 'sent' AND created_at >= ?`, + customerID, eventType, since.UTC().Format("2006-01-02 15:04:05")).Scan(&n) + return n, err +}