feat: add TLS reporting posture summaries

docs/index.md

@@ -25,4 +25,6 @@ For installation instructions, check the [Docker Setup](deployment/docker.md) or
 
 For Microsoft 365 setup, see [Microsoft 365 Mail Sources](user_guide/microsoft365.md).
 
+For SMTP TLS reporting imports and privacy controls, see [TLS Reports](user_guide/tls_reports.md).
+
 For aggregate-report parser support, known edge cases, and fixture guidance, see [DMARC Aggregate Format Compatibility](reference/dmarc-compatibility.md).

docs/milestones.md

@@ -220,7 +220,7 @@ Goal: turn DMARQ into a broader email authentication posture console (still priv
 
 Planned:
 - MTA-STS posture: delivered cached `_mta-sts` TXT checks, HTTPS policy validation, domain-detail evidence, and operator guidance for missing, invalid, or non-enforcing policies. Optional helper tooling remains a future enhancement.
-- TLS reporting posture: ingest and summarize TLS report data (where available) with actionable failure grouping.
+- TLS reporting posture: delivered authenticated TLS-RPT upload for `.json`, `.json.gz`, and `.zip` attachments; duplicate-safe persistence by report ID and policy domain; daily session trends; top failure-cause grouping; affected-domain summaries; and explicit privacy controls that avoid storing message content or recipient data.
 - BIMI posture: record validation + readiness checks + operator guidance.
 - Extended DNS checks that support the posture surface (e.g., MX/BIMI; optional DANE/TLSA where relevant).
 

docs/reference/api.md

@@ -259,6 +259,38 @@ Uploads a new DMARC report for processing.
 }
 ```
 
+### TLS Reports
+
+#### Upload TLS Report
+
+```
+POST /tls-reports/upload
+```
+
+Uploads an SMTP TLS Reporting aggregate attachment. Supported file types are
+`.json`, `.json.gz`, and `.zip`.
+
+**Example Response:**
+```json
+{
+  "success": true,
+  "report_id": "tls-report-20260520",
+  "policies_created": 1,
+  "policies_skipped": 0,
+  "duplicate": false,
+  "message": "TLS report imported."
+}
+```
+
+#### Summarize TLS Reports
+
+```
+GET /tls-reports/summary?domain=example.com&days=30
+```
+
+Returns aggregate TLS trends, top failure causes, affected domains, and the
+privacy controls for stored TLS-RPT data.
+
 ### Statistics
 
 #### Compliance Summary
@@ -413,4 +445,4 @@ Supported events:
 - `report.processed` - When a new report is processed
 - `compliance.threshold` - When compliance falls below threshold
 - `domain.added` - When a domain is added
-- `domain.removed` - When a domain is removed
+- `domain.removed` - When a domain is removed

docs/user_guide/tls_reports.md

@@ -0,0 +1,53 @@
+# TLS Reports
+
+DMARQ can import SMTP TLS Reporting (TLS-RPT) JSON aggregates and summarize
+delivery security failures alongside the existing DMARC posture views.
+
+## Importing TLS Reports
+
+Open **TLS Reports** and upload a `.json`, `.json.gz`, or `.zip` TLS-RPT
+attachment. A single file can contain multiple policy domains; DMARQ stores
+each policy-domain entry independently and skips duplicates by `report-id` plus
+policy domain.
+
+Imported reports appear in the same page as:
+
+- daily successful and failed TLS session trends
+- top TLS failure causes grouped by `result-type`
+- affected policy domains with failure rates
+- receiving MX hostnames and reason codes when reporters include them
+
+## API
+
+TLS reporting endpoints require the same admin authentication as other
+operational endpoints:
+
+- `POST /api/v1/tls-reports/upload` imports one TLS-RPT attachment.
+- `GET /api/v1/tls-reports` lists stored TLS report policy entries.
+- `GET /api/v1/tls-reports/summary?domain=example.com&days=30` returns trends,
+  top failure causes, and affected domains.
+
+## Retention and Privacy
+
+DMARQ stores only aggregate TLS reporting posture data:
+
+- report ID
+- reporting organization and contact info
+- policy domain and policy type
+- report date range
+- successful and failed session counts
+- grouped failure result type and failed-session count
+- sending MTA IP, receiving MX hostname, HELO, or IP when supplied by the report
+- failure reason code and grouped diagnostic text
+
+DMARQ does not store:
+
+- message bodies
+- message subjects
+- sender or recipient addresses
+- recipient local-parts
+- raw uploaded attachments
+- mailbox credentials or source message identifiers
+
+Use normal database backup and retention processes to control how long imported
+TLS-RPT aggregates remain available.