Harden send_mail API and TLS configuration

Author: lovasoa

Cargo.lock

@@ -79,7 +79,14 @@ openidconnect = { version = "4.0.0", default-features = false, features = ["acce
 encoding_rs = "0.8.35"
 odbc-sys = { version = "0", optional = true }
 regex = "1"
-lettre = { version = "0.11", default-features = false, features = ["builder", "smtp-transport", "tokio1", "tokio1-native-tls"] }
+lettre = { version = "0.11", default-features = false, features = [
+    "aws-lc-rs",
+    "builder",
+    "rustls-native-certs",
+    "smtp-transport",
+    "tokio1-rustls",
+    "webpki-roots",
+] }
 
 # OpenTelemetry / tracing
 tracing = "0.1"

Cargo.toml

@@ -41,9 +41,11 @@ Here are the available configuration options and their default values:
 | `environment`                                 | development                                                 | The environment in which SQLPage is running. Can be either `development` or `production`. In `production` mode, SQLPage will hide error messages and stack traces from the user, and will cache sql files in memory to avoid reloading them from disk. |
 | `cache_stale_duration_ms`                     | 1000 (prod), 0 (dev)                                        | The duration in milliseconds that a file can be cached before its freshness is checked against the filesystem. Defaults to 1000ms (1 second) in production and 0ms in development. |
 | `content_security_policy`                     | `script-src 'self' 'nonce-{NONCE}'`                          | The [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) to set in the HTTP headers. If you get CSP errors in the browser console, you can set this to the empty string to disable CSP. If you want a custom CSP that contains a nonce, include the `'nonce-{NONCE}'` directive in your configuration string and it will be populated with a random value per request.                                                                                                           |
-| `smtp_host`                                  |                                                              | SMTP server used by the `sqlpage.send_mail` function. Accepts only a host name or `host:port`; if no port is provided, SQLPage uses port 25. Set with `SMTP_HOST` in the environment. |
+| `smtp_host`                                  |                                                              | SMTP server host used by the `sqlpage.send_mail` function. Set with `SMTP_HOST` in the environment. |
+| `smtp_port`                                  | 25 (`none`), 465 (`tls`), or 587 (`starttls`)                | SMTP server port. The default depends on `smtp_tls_mode`. Set this explicitly for relays using a nonstandard port. |
 | `smtp_username`                              |                                                              | Optional SMTP user name for `sqlpage.send_mail`. When set, SQLPage authenticates to `SMTP_HOST` using this user name and `smtp_password`. Credentials require `smtp_tls_mode` to be `starttls` or `tls`. |
-| `smtp_password`                              |                                                              | Optional SMTP password for `sqlpage.send_mail` when `smtp_username` is set. |
+| `smtp_password`                              |                                                              | Optional SMTP password for `sqlpage.send_mail`. `smtp_username` and `smtp_password` must be configured together. |
+| `smtp_from`                                  |                                                              | Default sender address for `sqlpage.send_mail`, optionally including a display name. Individual messages can override it with their `from` property. |
 | `smtp_tls_mode`                              | `starttls`                                                   | Encryption mode for `sqlpage.send_mail`: `starttls` requires a STARTTLS upgrade, `tls` uses TLS from connection start, and `none` permits plaintext only without credentials for trusted local SMTP servers. |
 | `system_root_ca_certificates`                 | false                                                      | Whether to use the system root CA certificates to validate SSL certificates when making http requests with `sqlpage.fetch`. If set to false, SQLPage will use its own set of root CA certificates. If the `SSL_CERT_FILE` or `SSL_CERT_DIR` environment variables are set, they will be used instead of the system root CA certificates. |
 | `max_recursion_depth`                         | 10                                                           | Maximum depth of recursion allowed in the `run_sql` function. Maximum value is 255. |

configuration.md

@@ -2,40 +2,39 @@ INSERT INTO sqlpage_functions (
         "name",
         "introduced_in_version",
         "icon",
-        "description_md",
-        "return_type"
+        "description_md"
     )
 VALUES (
         'send_mail',
         '0.45.0',
         'mail',
         'Sends an email using the SMTP server configured with `SMTP_HOST`.
 
-`SMTP_HOST` must contain only a host name or `host:port`; URL schemes and paths are rejected. When no port is specified, SQLPage uses port 25.
+`SMTP_HOST` contains the relay host name. Set `SMTP_PORT` when the relay does not use the default for the selected encryption mode: 587 for `starttls`, 465 for `tls`, or 25 for `none`.
 
 `SMTP_TLS_MODE` defaults to `starttls`, which requires a STARTTLS upgrade before sending email or credentials. Set it to `tls` for implicit TLS, commonly used on port 465. Plaintext mode (`none`) is allowed only without credentials and should be used only for trusted local SMTP servers.
 
 If your SMTP server requires authentication, configure `SMTP_USERNAME` and `SMTP_PASSWORD` as well.
 
 The function accepts a single JSON object argument. The required properties are:
 
-- `recipient`: email address to send to, optionally including a display name such as `"Jane Doe <jane@example.com>"`.
+- `to`: email address to send to, optionally including a display name such as `"Jane Doe <jane@example.com>"`.
 - `subject`: email subject.
 - `body`: plain text email body.
 
 Optional properties:
 
-- `sender`: sender address. Defaults to `SQLPage <sqlpage@localhost>`.
+- `from`: sender address. It may be omitted when `SMTP_FROM` configures a default sender.
 - `reply_to`: reply-to address.
 
-After the SMTP server accepts the message, the function returns its JSON argument unchanged. It returns `NULL` when passed `NULL`, and raises an error if the message cannot be sent.
+The function returns `NULL` after the SMTP relay accepts the message and raises an error if the message cannot be sent. The argument is required; passing `NULL` is an error.
 
 ### Example
 
 ```sql
 set message = json_object(
-    ''recipient'', ''admin@example.com'',
-    ''sender'', ''contact@example.com'',
+    ''to'', ''admin@example.com'',
+    ''from'', ''contact@example.com'',
     ''subject'', ''New contact form message'',
     ''body'', ''Hello from SQLPage!''
 );
@@ -50,16 +49,15 @@ select ''email'' as name, ''email'' as type, true as required;
 select ''message'' as name, ''textarea'' as type, true as required;
 
 set mail = json_object(
-    ''recipient'', ''admin@example.com'',
+    ''to'', ''admin@example.com'',
     ''reply_to'', $email,
     ''subject'', ''Website contact form'',
     ''body'', $message
 );
 select sqlpage.send_mail($mail)
 where $message is not null;
 ```
-',
-        'JSON'
+'
     );
 
 INSERT INTO sqlpage_function_parameters (
@@ -73,6 +71,6 @@ VALUES (
         'send_mail',
         1,
         'message',
-        'A JSON object containing the email to send. Required properties are `recipient`, `subject`, and `body`. Optional properties are `sender` and `reply_to`.',
+        'A JSON object containing the email to send. Required properties are `to`, `subject`, and `body`. Optional properties are `from` (required unless `SMTP_FROM` is configured) and `reply_to`. Unknown properties are rejected to catch misspellings.',
         'JSON'
     );

examples/official-site/sqlpage/migrations/75_send_mail.sql

@@ -10,22 +10,22 @@ docker compose up
 
 Open http://localhost:8080 to send an email, then inspect it in the Mailpit inbox at http://localhost:8025.
 
-The SMTP server is configured in [`docker-compose.yml`](./docker-compose.yml) with `SMTP_HOST=mailpit:1025` and `SMTP_TLS_MODE=none`. Plaintext mode is intended only for trusted local SMTP servers such as Mailpit.
+The SMTP server is configured in [`docker-compose.yml`](./docker-compose.yml) with `SMTP_HOST=mailpit`, `SMTP_PORT=1025`, and `SMTP_TLS_MODE=none`. Plaintext mode is intended only for trusted local SMTP servers such as Mailpit.
 
 For a remote SMTP relay, keep the default `SMTP_TLS_MODE=starttls`, or set it to `tls` when the relay requires implicit TLS. Configure `SMTP_USERNAME` and `SMTP_PASSWORD` when authentication is required; SQLPage rejects credentials in plaintext mode.
 
 The form handler sends the message with a single function call:
 
 ```sql
 set message = json_object(
-    'recipient', :recipient,
-    'sender', :sender,
+    'to', :recipient,
+    'from', :sender,
     'subject', :subject,
     'body', :body
 );
-set sent_message = sqlpage.send_mail($message);
+set _ = sqlpage.send_mail($message);
 ```
 
-After the SMTP server accepts the email, `sqlpage.send_mail` returns the message JSON unchanged. It raises an error when delivery to the SMTP server fails.
+`sqlpage.send_mail` returns `NULL` after the SMTP relay accepts the message. It raises an error when the relay rejects the message or cannot be reached, so statements after the call run only on success.
 
 Do not expose an unrestricted form like this publicly. In production, authenticate users, restrict recipients, validate input, and add rate limiting to prevent abuse.

examples/sending emails/README.md

@@ -4,7 +4,8 @@ services:
     ports:
       - "8080:8080"
     environment:
-      SMTP_HOST: mailpit:1025
+      SMTP_HOST: mailpit
+      SMTP_PORT: 1025
       SMTP_TLS_MODE: none
     volumes:
       - .:/var/www

examples/sending emails/docker-compose.yml

@@ -1,6 +1,6 @@
 set message = json_object(
-    'recipient', :recipient,
-    'sender', :sender,
+    'to', :recipient,
+    'from', :sender,
     'subject', :subject,
     'body', :body
 );
@@ -9,8 +9,7 @@ set sent_message = sqlpage.send_mail($message);
 select
     'alert' as component,
     'success' as color,
-    'Email sent successfully' as title
-where $sent_message is not null;
+    'Email sent successfully' as title;
 
 select 'button' as component;
 select 'Send another email' as title, 'index.sql' as link;