Scheduled reports and the weekly digest

An administrator picks sections, a schedule (daily, weekly or monthly,
at a time in a time zone) and recipients, who must be accounts on this
server. Every node looks for due reports once a minute; a run is claimed
with the task lock, keyed by report and due time, and recorded on the
report, so it goes once. The report is built from what the server
already keeps: mail flow, the queue, spoofing from received DMARC
reports, TLS failures, deliverability findings and what changed since
the last run, security counters, people near their quota, and expiring
certificates. It is mailed as text and HTML with optional CSV
attachments, DKIM-signed; a sender domain without a key fails the run
with that reason instead of sending unsigned.

The weekly digest is a built-in report on every server, on by default:
every section, Mondays 07:00 UTC, to the system administrators. It can
be changed or turned off, not deleted. A tenant administrator makes and
sees only their own tenant's reports, which leave out server-wide
sections.

New: inbuxa:ScheduledReport and inbuxa:ScheduledReportSettings, the
sysScheduledReportGet and sysScheduledReportUpdate permissions (granted
once to existing administrator roles), privacy catalog entries, and a
system test. Spec: inbuxa-drafts specs/scheduled-reports.md.

tests/src/system/mod.rs

@@ -18,6 +18,7 @@ pub mod compliance; // inbuxa: the compliance roles
 pub mod mail_rules; // inbuxa: DLP and mail flow rules
 pub mod security_acceptances; // inbuxa: accepted security to-do items
 pub mod deliverability; // inbuxa: the deliverability check
+pub mod scheduled_reports; // inbuxa: scheduled reports and the weekly digest
 pub mod journal; // inbuxa: journaling
 pub mod audit; // inbuxa: the audit log
 pub mod authorization;

tests/src/system/scheduled_reports.rs

@@ -0,0 +1,366 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Coffey Labs LLC
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+
+//! Scheduled reports and the weekly digest (scheduled-reports spec): the
+//! digest every server has, making and changing reports, who they may go
+//! to, Send now, and what a tenant administrator sees.
+
+use crate::utils::{
+    account::Account,
+    server::{TestServer, TestServerBuilder},
+};
+use registry::schema::{
+    prelude::{ObjectType, Property},
+    structs::{CertificateManagement, DkimManagement, DnsManagement, Domain, Tenant, UserRoles},
+};
+use serde_json::{Value, json};
+use std::time::{Duration, Instant};
+
+const USING: &[&str] = &[
+    "urn:ietf:params:jmap:core",
+    "urn:inbuxa:jmap",
+    "urn:inbuxa:jmap:registry",
+];
+
+async fn call(account: &Account, method: &str, mut arguments: Value) -> (String, Value) {
+    if arguments.get("accountId").is_none() {
+        arguments["accountId"] = account.id_string().into();
+    }
+    let response = account
+        .jmap_request(USING, json!([[method, arguments, "0"]]))
+        .await;
+    let call = response
+        .0
+        .pointer("/methodResponses/0")
+        .cloned()
+        .unwrap_or_else(|| panic!("{method}: {}", response.0));
+    (
+        call[0].as_str().unwrap_or_default().to_string(),
+        call[1].clone(),
+    )
+}
+
+async fn reports(account: &Account) -> Vec<Value> {
+    let (_, response) = call(account, "inbuxa:ScheduledReport/get", json!({"ids": null})).await;
+    response["list"].as_array().cloned().unwrap_or_default()
+}
+
+pub async fn test(test: &mut TestServer) {
+    println!("Running scheduled reports tests...");
+    let admin = test.account("[email protected]");
+    let me = "[email protected]";
+
+    // --- The weekly digest every server has (RP-21) ------------------------
+    let list = reports(admin).await;
+    let digest = list
+        .iter()
+        .find(|r| r["builtIn"] == true)
+        .unwrap_or_else(|| panic!("no digest: {list:?}"));
+    let digest_id = digest["id"].as_str().unwrap().to_string();
+    assert_eq!(digest["enabled"], true, "{digest}");
+    assert_eq!(digest["sections"].as_array().unwrap().len(), 8, "{digest}");
+    assert_eq!(digest["schedule"]["frequency"], "weekly", "{digest}");
+    assert_eq!(digest["schedule"]["weekday"], 1, "{digest}");
+    assert_eq!(digest["schedule"]["hour"], 7, "{digest}");
+    assert!(digest["nextRunAt"].is_string(), "{digest}");
+
+    let (_, response) = call(
+        admin,
+        "inbuxa:ScheduledReport/set",
+        json!({"destroy": [digest_id]}),
+    )
+    .await;
+    assert!(
+        response["notDestroyed"][&digest_id].is_object(),
+        "the digest was deleted: {response}"
+    );
+    let (_, response) = call(
+        admin,
+        "inbuxa:ScheduledReport/set",
+        json!({"update": {&digest_id: {"recipients": [me]}}}),
+    )
+    .await;
+    assert!(
+        response["notUpdated"][&digest_id].is_object(),
+        "the digest took recipients: {response}"
+    );
+    // It can be changed and turned off
+    let (_, response) = call(
+        admin,
+        "inbuxa:ScheduledReport/set",
+        json!({"update": {&digest_id: {"enabled": false, "schedule": {
+            "frequency": "weekly", "weekday": 5, "hour": 16, "minute": 30,
+            "timeZone": "America/Phoenix"
+        }}}}),
+    )
+    .await;
+    assert!(
+        response["updated"][&digest_id].is_null() && response["notUpdated"].is_null(),
+        "{response}"
+    );
+    let digest = reports(admin)
+        .await
+        .into_iter()
+        .find(|r| r["id"] == digest_id.as_str())
+        .unwrap();
+    assert_eq!(digest["enabled"], false, "{digest}");
+    assert!(
+        digest["nextRunAt"].is_null(),
+        "an off report has no next run: {digest}"
+    );
+    assert_eq!(digest["schedule"]["timeZone"], "America/Phoenix");
+
+    // --- Making a report: what's checked (RP-15, RP-23) ---------------------
+    let good = json!({
+        "name": "Daily storage",
+        "sections": ["storage", "certificates"],
+        "schedule": {"frequency": "daily", "hour": 6, "minute": 0, "timeZone": "Europe/Amsterdam"},
+        "recipients": [me],
+        "attachCsv": true
+    });
+    let mut outside = good.clone();
+    outside["recipients"] = json!(["[email protected]"]);
+    let mut bad_zone = good.clone();
+    bad_zone["schedule"]["timeZone"] = json!("Mars/Olympus");
+    let mut no_sections = good.clone();
+    no_sections["sections"] = json!([]);
+    let mut unknown_section = good.clone();
+    unknown_section["sections"] = json!(["weather"]);
+    let (_, response) = call(
+        admin,
+        "inbuxa:ScheduledReport/set",
+        json!({"create": {
+            "outside": outside, "zone": bad_zone, "empty": no_sections,
+            "unknown": unknown_section, "good": good
+        }}),
+    )
+    .await;
+    for refused in ["outside", "zone", "empty", "unknown"] {
+        assert!(
+            response["notCreated"][refused].is_object(),
+            "{refused} was accepted: {response}"
+        );
+    }
+    assert!(
+        response["notCreated"]["outside"]["description"]
+            .as_str()
+            .unwrap_or_default()
+            .contains("isn't an account on this server"),
+        "{response}"
+    );
+    let id = response["created"]["good"]["id"]
+        .as_str()
+        .unwrap_or_else(|| panic!("not created: {response}"))
+        .to_string();
+    assert!(
+        response["created"]["good"]["nextRunAt"].is_string(),
+        "{response}"
+    );
+
+    // The server's own fields can't be set
+    let (_, response) = call(
+        admin,
+        "inbuxa:ScheduledReport/set",
+        json!({"update": {&id: {"runs": []}}}),
+    )
+    .await;
+    assert!(response["notUpdated"][&id].is_object(), "{response}");
+
+    // --- Send now (RP-18), never unsigned (RP-14) ----------------------------
+    async fn send_now(admin: &Account, id: &str, runs_before: usize) -> Value {
+        let (_, response) = call(
+            admin,
+            "inbuxa:ScheduledReport/set",
+            json!({"update": {id: {"sendNow": true}}}),
+        )
+        .await;
+        assert!(response["notUpdated"].is_null(), "{response}");
+        let deadline = Instant::now() + Duration::from_secs(30);
+        loop {
+            let report = reports(admin)
+                .await
+                .into_iter()
+                .find(|r| r["id"] == id)
+                .unwrap();
+            let runs = report["runs"].as_array().cloned().unwrap_or_default();
+            if runs.len() > runs_before {
+                return runs[0].clone();
+            }
+            assert!(Instant::now() < deadline, "Send now never ran: {report}");
+            tokio::time::sleep(Duration::from_millis(250)).await;
+        }
+    }
+    // The default sender's domain has no DKIM key: refused, with the reason
+    let run = send_now(admin, &id, 0).await;
+    assert_eq!(run["byHand"], true, "{run}");
+    assert_eq!(run["status"], "failed", "{run}");
+    assert!(
+        run["reason"].as_str().unwrap_or_default().contains("DKIM"),
+        "{run}"
+    );
+    // A domain with keys signs it, and the queue takes it
+    let (_, response) = call(
+        admin,
+        "x:Domain/query",
+        json!({"filter": {"name": "example.com"}}),
+    )
+    .await;
+    let domain_id = response["ids"][0]
+        .as_str()
+        .unwrap_or_else(|| panic!("{response}"))
+        .parse::<types::id::Id>()
+        .unwrap();
+    admin.create_dkim_signatures(domain_id).await;
+    let (_, response) = call(
+        admin,
+        "inbuxa:ScheduledReportSettings/set",
+        json!({"update": {"singleton": {"fromAddress": "[email protected]"}}}),
+    )
+    .await;
+    assert!(response["notUpdated"].is_null(), "{response}");
+    let run = send_now(admin, &id, 1).await;
+    assert_eq!(run["status"], "sent", "{run}");
+    assert_eq!(run["recipients"], 1, "{run}");
+    assert!(run["size"].as_u64().unwrap() > 500, "{run}");
+
+    // --- Who it comes from (RP-20) -------------------------------------------
+    let (_, response) = call(
+        admin,
+        "inbuxa:ScheduledReportSettings/get",
+        json!({"ids": null}),
+    )
+    .await;
+    let settings = &response["list"][0];
+    assert_eq!(settings["fromName"], "inbuxa reports", "{response}");
+    assert_eq!(settings["fromAddress"], "[email protected]", "{response}");
+    let (_, response) = call(
+        admin,
+        "inbuxa:ScheduledReportSettings/set",
+        json!({"update": {"singleton": {"fromAddress": "not an address"}}}),
+    )
+    .await;
+    assert!(
+        response["notUpdated"]["singleton"].is_object(),
+        "{response}"
+    );
+
+    // --- A tenant administrator (RP-22) --------------------------------------
+    let tenant = admin
+        .registry_create_object(Tenant {
+            name: "Reports tenant".to_string(),
+            ..Default::default()
+        })
+        .await;
+    admin
+        .registry_create_object(Domain {
+            name: "reports.example.org".to_string(),
+            is_enabled: true,
+            member_tenant_id: Some(tenant),
+            certificate_management: CertificateManagement::Manual,
+            dns_management: DnsManagement::Manual,
+            dkim_management: DkimManagement::Manual,
+            ..Default::default()
+        })
+        .await;
+    let t_admin = admin
+        .create_user_account(
+            "[email protected]",
+            "tenant-admin-secret-6120",
+            "Tenant admin",
+            &[],
+            vec![],
+        )
+        .await;
+    admin
+        .registry_update_object(
+            ObjectType::Account,
+            t_admin.id(),
+            json!({Property::Roles: UserRoles::Admin}),
+        )
+        .await;
+    assert!(
+        reports(&t_admin).await.is_empty(),
+        "a tenant administrator saw the server's reports"
+    );
+    let (_, response) = call(
+        &t_admin,
+        "inbuxa:ScheduledReport/set",
+        json!({"create": {"mine": {
+            "name": "Our domains",
+            "sections": ["spoofing", "deliverability", "mailFlow"],
+            "schedule": {"frequency": "monthly", "dayOfMonth": 1, "hour": 8, "minute": 0, "timeZone": "UTC"},
+            "recipients": ["[email protected]"]
+        }}}),
+    )
+    .await;
+    let mine = response["created"]["mine"]["id"]
+        .as_str()
+        .unwrap_or_else(|| panic!("tenant report not created: {response}"))
+        .to_string();
+    let seen = reports(&t_admin).await;
+    assert_eq!(seen.len(), 1, "{seen:?}");
+    assert_eq!(seen[0]["memberTenantId"], tenant.to_string(), "{seen:?}");
+    // The system administrator sees it too, and the tenant can't touch theirs
+    assert!(
+        reports(admin)
+            .await
+            .iter()
+            .any(|r| r["id"] == mine.as_str())
+    );
+    let (_, response) = call(
+        &t_admin,
+        "inbuxa:ScheduledReport/set",
+        json!({"update": {&id: {"enabled": false}}}),
+    )
+    .await;
+    assert!(response["notUpdated"][&id].is_object(), "{response}");
+    let (name, response) = call(
+        &t_admin,
+        "inbuxa:ScheduledReportSettings/set",
+        json!({"update": {"singleton": {"fromName": "Tenant"}}}),
+    )
+    .await;
+    assert_eq!(name, "error", "a tenant changed the sender: {response}");
+
+    // --- Deleting ------------------------------------------------------------
+    let (_, response) = call(
+        admin,
+        "inbuxa:ScheduledReport/set",
+        json!({"destroy": [&id, &mine]}),
+    )
+    .await;
+    assert_eq!(
+        response["destroyed"].as_array().map(|d| d.len()),
+        Some(2),
+        "{response}"
+    );
+    // Put the digest back as it was for the tests that follow
+    call(
+        admin,
+        "inbuxa:ScheduledReport/set",
+        json!({"update": {&digest_id: {"enabled": true, "schedule": {
+            "frequency": "weekly", "weekday": 1, "hour": 7, "minute": 0, "timeZone": "UTC"
+        }}}}),
+    )
+    .await;
+}
+
+#[ignore]
+#[tokio::test(flavor = "multi_thread")]
+pub async fn scheduled_reports_tests() {
+    let mut test = TestServerBuilder::new("scheduled_reports_tests")
+        .await
+        .with_default_listeners()
+        .await
+        .build()
+        .await;
+    let admin = test.create_admin_account("[email protected]").await;
+    test.insert_account(admin);
+    self::test(&mut test).await;
+    if test.is_reset() {
+        test.temp_dir.delete();
+    }
+}