From 699f0984cfabe4c8ba19bb50d5f14d8c96ea82b2 Mon Sep 17 00:00:00 2001 From: Will Calcote <53543954+willcalcote@users.noreply.github.com> Date: Fri, 4 Sep 2026 04:10:45 -0500 Subject: [PATCH] docs(cloud): stop documenting the email config test as an unauthenticated probe Symptom - the self-hosted SMTP guide showed `GET /api/system/email/test` being called with no credential, and presented a success body containing `smtp_host`, `smtp_port` and `smtp_username` as normal output. The troubleshooting checklist sent operators to that same unauthenticated probe. The page was documentation for a defect rather than for the endpoint. Root cause - the route was registered bare in meshery-cloud's router while its POST sibling carried `AuthorizationMiddlewareForAdmin`, and the handler restated the configuration it had just validated. `SMTP_USERNAME` is an email address, so any caller on the internet could read it. This page faithfully described that behaviour. Fix - the page now shows the GET carrying an admin bearer token, states that both verbs are provider-admin only, and gives the verdict-only success body. Verified against the meshery-cloud change itself rather than taken on description: both verbs now attach `AuthorizationMiddlewareForAdmin` in `server/router/router.go`, and `TestEmailConfigurationHandler` returns `status`, `message` and `timestamp` alone. Two response examples were also wrong in shape, checked against the same handler, so they are corrected while the section is being rewritten rather than left as newly-adjacent errors: - the failure path uses `http.Error`, so it answers 500 with plain text, not the JSON object the page showed; - refusals come from Echo's default error handler as `{"message": ...}`, 401 unauthenticated and 403 for a non-admin. Both are now shown, so an operator can tell a missing credential from a missing role. The `password_length=16` field in the SMTP configuration debug log sample is gone too - the same meshery-cloud commit stopped logging the length of `SMTP_PASSWORD`, since the length of a secret narrows a brute-force search and `password_set` is the only thing that line was diagnosing. Left alone deliberately - the `smtp_username=sender@domain.com` in the send-failure log sample. That is a server-side log an operator reads from their own deployment, on the send path rather than the test endpoint, and it is unchanged by the fix; it implies nothing about what the endpoint returns. Renaming the heading to mark it admin-only would have moved its anchor, which is linked from outside this repository, so the old slug is pinned with `{#1-email-configuration-test-endpoint}`. Proved by building master and this branch to separate directories and diffing every `

`-`

` `id=` in the generated page: no anchor lost, none added. Watch for - the POST section a few lines below still documents `{"error": "Unauthorized: provider admin role required"}` and two sibling `{"error": ...}` bodies, which are not what that handler emits either, and the send-failure sample is labelled `ERROR` where the server logs it at `DEBUG`. Both predate this change and sit outside the scope given, so they are reported here rather than fixed. Depends on the meshery-cloud change; must not merge before it lands. Signed-off-by: Will Calcote <53543954+willcalcote@users.noreply.github.com> --- .../guides/self-hosted/operating/smtp.md | 42 ++++++++++++++----- 1 file changed, 31 insertions(+), 11 deletions(-) diff --git a/content/en/cloud/guides/self-hosted/operating/smtp.md b/content/en/cloud/guides/self-hosted/operating/smtp.md index 42640eb2992d..1f9035b72cd3 100644 --- a/content/en/cloud/guides/self-hosted/operating/smtp.md +++ b/content/en/cloud/guides/self-hosted/operating/smtp.md @@ -27,12 +27,16 @@ LOG_LEVEL=5 ## Testing Email Configuration -### 1. Email Configuration Test Endpoint +### 1. Email Configuration Test Endpoint (Provider Admin Only) {#1-email-configuration-test-endpoint} -Test the basic email configuration without sending actual emails: +Check that the four `SMTP_*` values are configured, without sending an email. +**Both verbs of this endpoint require authentication and the provider admin +role**, so the `GET` must carry a credential. It validates configuration only - +it does not dial the SMTP server. ```bash -curl -X GET "https://your-domain.com/api/system/email/test" +curl -X GET "https://your-domain.com/api/system/email/test" \ + -H "Authorization: Bearer YOUR_JWT_TOKEN" ``` **Expected Response (Success):** @@ -40,17 +44,33 @@ curl -X GET "https://your-domain.com/api/system/email/test" { "status": "success", "message": "Email configuration is valid", - "timestamp": "1695312000", - "smtp_host": "smtp.gmail.com", - "smtp_port": "587", - "smtp_username": "your-email@domain.com" + "timestamp": "1695312000" +} +``` + +The response carries the verdict only. It does not report `smtp_host`, +`smtp_port` or `smtp_username`: those are the deployment's own relay settings, +and `SMTP_USERNAME` is an email address. Read the configured values from your +deployment configuration instead. + +**Expected Response (Error):** `500 Internal Server Error`, as plain text +rather than JSON: + +```text +Email configuration verification failed: SMTP configuration error for field 'SMTP_HOST' +``` + +**Expected Response (Unauthenticated):** `401 Unauthorized` +```json +{ + "message": "user must be logged in to perform this operation" } ``` -**Expected Response (Error):** +**Expected Response (Authenticated, not a provider admin):** `403 Forbidden` ```json { - "error": "Email configuration test failed: SMTP_HOST environment variable is not set" + "message": "user you@example.com must be Provider Admin to perform this operation" } ``` @@ -126,7 +146,7 @@ When `LOG_LEVEL=5`, you'll see detailed debug logs for email operations: ### 1. SMTP Configuration Validation ```log -DEBUG SMTP Configuration Debug host=smtp.gmail.com port=587 username=user@domain.com password_set=true password_length=16 +DEBUG SMTP Configuration Debug host=smtp.gmail.com port=587 username=user@domain.com password_set=true ``` ### 2. Template Processing @@ -254,7 +274,7 @@ Consider setting up monitoring for email-related metrics: - [ ] Check `LOG_LEVEL` is set to 5 or 6 for debug logging - [ ] Verify all SMTP environment variables are configured -- [ ] Test email configuration using `/api/system/email/test` endpoint +- [ ] Test email configuration using the provider-admin-only `/api/system/email/test` endpoint, authenticating the request - [ ] Check network connectivity to SMTP server - [ ] Validate email template files exist and are accessible - [ ] Verify recipient email addresses are valid