From 39408dffe8383d6138f1ce6be8c89f9f82a4348d Mon Sep 17 00:00:00 2001 From: Dmitry Verkhoturov Date: Thu, 28 May 2026 18:56:33 +0100 Subject: [PATCH] fix: parameter docs + --help text inconsistencies (audit) (#2077) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * fix: address parameter docs and --help text inconsistencies Audit findings from comparing site/src/docs/configuration/parameters/ against the backend flag tags. Docs (parameters/index.md): - image.bolt.file default was `/var/pictures.db` (absolute, looks like a system path); actual default is `./var/pictures.db` (relative, under the working dir). - notify.webhook.template default was shown as `{"text": {{.Text | escapeJSONString}}}` — both the function name doesn't exist and the unescaped pipe inside the table cell broke the Description column count for that row. Real default is the literal `{"text": "{{.Text}}"}`. - "Custom OAuth2 integration currently supports only one custom provider at a time" was a free-standing paragraph wedged between two table rows. kramdown terminated the table on that paragraph and restarted a new headerless table for the rest of the rows. Moved it to its own subsection after the table so the table stays contiguous. Backend --help text (server.go): - allowed-hosts description ended with a stray double apostrophe in `CSP 'frame-ancestors''` (typo). - Deprecated auth.email.{port,passwd,user,tls} flag descriptions were shuffled — port said "SMTP password", passwd said "SMTP port", user said "enable TLS", tls said "SMTP TCP connection timeout". Fixed each to match the flag it's actually describing. Docs already had the correct descriptions for these deprecated flags. * fix: webhook template flag default override masking safe fallback Copilot flagged the audit's "real default" claim and was right. server.go:286 had default:"{\"text\": \"{{.Text}}\"}" — the literal, JSON-unsafe template that produces invalid JSON if a comment contains a quote or newline. The notify package (webhook.go:50) has a safer fallback: if params.Template == "" { params.Template = webhookDefaultTemplate } where webhookDefaultTemplate is {"text": {{.Text | escapeJSONString}}}. But go-flags applies its default tag at parse time, so the field is never empty when the user omits --notify.webhook.template, and the safer fallback never runs. Drop the unsafe default tag so the webhook package's escapeJSONString-based default takes effect. Also: - fix the --help description (was "webhook authentication template", but it's a payload template, not an auth one; same for headers). - update parameters/index.md to document the actual safe default ({{.Text | escapeJSONString}}); escape the cell's | as \| so kramdown doesn't treat it as a column separator. - typo: "bellow" -> "below" in the headers env-delim comment. --- backend/app/cmd/server.go | 14 +++++++------- site/src/docs/configuration/parameters/index.md | 11 ++++++----- 2 files changed, 13 insertions(+), 12 deletions(-) diff --git a/backend/app/cmd/server.go b/backend/app/cmd/server.go index 9beab703..89b90652 100644 --- a/backend/app/cmd/server.go +++ b/backend/app/cmd/server.go @@ -90,7 +90,7 @@ type ServerCommand struct { EnableEmoji bool `long:"emoji" env:"EMOJI" description:"enable emoji"` SimpleView bool `long:"simple-view" env:"SIMPLE_VIEW" description:"minimal comment editor mode"` ProxyCORS bool `long:"proxy-cors" env:"PROXY_CORS" description:"disable internal CORS and delegate it to proxy"` - AllowedHosts []string `long:"allowed-hosts" env:"ALLOWED_HOSTS" description:"limit hosts/sources allowed to embed comments via CSP 'frame-ancestors''" env-delim:","` + AllowedHosts []string `long:"allowed-hosts" env:"ALLOWED_HOSTS" description:"limit hosts/sources allowed to embed comments via CSP 'frame-ancestors'" env-delim:","` SubscribersOnly bool `long:"subscribers-only" env:"SUBSCRIBERS_ONLY" description:"enable commenting only for Patreon subscribers"` DisableSignature bool `long:"disable-signature" env:"DISABLE_SIGNATURE" description:"disable server signature in headers"` DisableFancyTextFormatting bool `long:"disable-fancy-text-formatting" env:"DISABLE_FANCY_TEXT_FORMATTING" description:"disable fancy comments text formatting (replacement of quotes, dashes, fractions, etc)"` @@ -123,10 +123,10 @@ type ServerCommand struct { Subject string `long:"subj" env:"SUBJ" default:"remark42 confirmation" description:"email's subject"` ContentType string `long:"content-type" env:"CONTENT_TYPE" default:"text/html" description:"content type"` Host string `long:"host" env:"HOST" description:"[deprecated, use --smtp.host] SMTP host"` - Port int `long:"port" env:"PORT" description:"[deprecated, use --smtp.port] SMTP password"` - SMTPPassword string `long:"passwd" env:"PASSWD" description:"[deprecated, use --smtp.password] SMTP port"` - SMTPUserName string `long:"user" env:"USER" description:"[deprecated, use --smtp.username] enable TLS"` - TLS bool `long:"tls" env:"TLS" description:"[deprecated, use --smtp.tls] SMTP TCP connection timeout"` + Port int `long:"port" env:"PORT" description:"[deprecated, use --smtp.port] SMTP port"` + SMTPPassword string `long:"passwd" env:"PASSWD" description:"[deprecated, use --smtp.password] SMTP password"` + SMTPUserName string `long:"user" env:"USER" description:"[deprecated, use --smtp.username] SMTP user name"` + TLS bool `long:"tls" env:"TLS" description:"[deprecated, use --smtp.tls] enable TLS"` TimeOut time.Duration `long:"timeout" env:"TIMEOUT" default:"10s" description:"[deprecated, use --smtp.timeout] SMTP TCP connection timeout"` MsgTemplate string `long:"template" env:"TEMPLATE" description:"[deprecated] message template file" default:"email_confirmation_login.html.tmpl"` } `group:"email" namespace:"email" env-namespace:"EMAIL"` @@ -283,8 +283,8 @@ type NotifyGroup struct { } `group:"slack" namespace:"slack" env-namespace:"SLACK"` Webhook struct { URL string `long:"url" env:"URL" description:"webhook URL for admin notifications"` - Template string `long:"template" env:"TEMPLATE" description:"webhook authentication template" default:"{\"text\": \"{{.Text}}\"}"` - Headers []string `long:"headers" description:"webhook authentication headers in format --notify.webhook.headers=Header1:Value1,Value2,... [$NOTIFY_WEBHOOK_HEADERS]"` // env NOTIFY_WEBHOOK_HEADERS split in code bellow to allow , inside "" + Template string `long:"template" env:"TEMPLATE" description:"webhook payload template (Go text/template); falls back to {\"text\": {{.Text | escapeJSONString}}} when empty"` + Headers []string `long:"headers" description:"webhook headers in format --notify.webhook.headers=Header1:Value1,Value2,... [$NOTIFY_WEBHOOK_HEADERS]"` // env NOTIFY_WEBHOOK_HEADERS split in code below to allow , inside "" Timeout time.Duration `long:"timeout" env:"TIMEOUT" description:"webhook timeout" default:"5s"` } `group:"webhook" namespace:"webhook" env-namespace:"WEBHOOK"` } diff --git a/site/src/docs/configuration/parameters/index.md b/site/src/docs/configuration/parameters/index.md index 1a46743c..a4e8ca0f 100644 --- a/site/src/docs/configuration/parameters/index.md +++ b/site/src/docs/configuration/parameters/index.md @@ -69,7 +69,7 @@ services: | image.fs.path | IMAGE_FS_PATH | `./var/pictures` | permanent location of images | | image.fs.staging | IMAGE_FS_STAGING | `./var/pictures.staging` | staging location of images | | image.fs.partitions | IMAGE_FS_PARTITIONS | `100` | number of image partitions | -| image.bolt.file | IMAGE_BOLT_FILE | `/var/pictures.db` | images bolt file location | +| image.bolt.file | IMAGE_BOLT_FILE | `./var/pictures.db` | images bolt file location | | image.rpc.api | IMAGE_RPC_API | | rpc extension api url | | image.rpc.timeout | IMAGE_RPC_TIMEOUT | | http timeout (default: 5s) | | image.rpc.auth_user | IMAGE_RPC_AUTH_USER | | basic auth user name | @@ -109,9 +109,6 @@ services: | auth.custom.name-field | AUTH_CUSTOM_NAME_FIELD | `name` | user info field used as display name | | auth.custom.picture-field | AUTH_CUSTOM_PICTURE_FIELD | `picture` | user info field used as avatar URL | | auth.custom.email-field | AUTH_CUSTOM_EMAIL_FIELD | `email` | user info field used as email | - -Custom OAuth2 integration currently supports only one custom provider at a time, and `AUTH_CUSTOM_NAME` must match `^[a-z0-9][a-z0-9_-]*$`. - | auth.telegram | AUTH_TELEGRAM | `false` | Enable Telegram auth (telegram.token must be present) | | auth.yandex.cid | AUTH_YANDEX_CID | | Yandex OAuth client ID | | auth.yandex.csec | AUTH_YANDEX_CSEC | | Yandex OAuth client secret | @@ -128,7 +125,7 @@ Custom OAuth2 integration currently supports only one custom provider at a time, | notify.slack.token | NOTIFY_SLACK_TOKEN | | Slack token | | notify.slack.chan | NOTIFY_SLACK_CHAN | `general` | Slack channel for admin notifications | | notify.webhook.url | NOTIFY_WEBHOOK_URL | | Webhook notification URL for admin notifications | -| notify.webhook.template | NOTIFY_WEBHOOK_TEMPLATE | `{"text": {{.Text | escapeJSONString}}}` | Webhook payload template | +| notify.webhook.template | NOTIFY_WEBHOOK_TEMPLATE | `{"text": {{.Text \| escapeJSONString}}}` | Webhook payload template (Go text/template) | | notify.webhook.headers | NOTIFY_WEBHOOK_HEADERS | | HTTP header in format Header1:Value1,Header2:Value2,... | | notify.webhook.timeout | NOTIFY_WEBHOOK_TIMEOUT | `5s` | Webhook connection timeout | | notify.email.from_address | NOTIFY_EMAIL_FROM | | from email address (e.g. `john.doe@example.com` or `"John Doe"`) | @@ -184,6 +181,10 @@ Custom OAuth2 integration currently supports only one custom provider at a time, - _multi_ parameters separated by `,` in the environment or repeated with command-line keys, like `--site=s1 --site=s2 ...` - _required_ parameters have to be presented in the environment or provided in the command-line +### Custom OAuth2 integration + +Custom OAuth2 integration currently supports only one custom provider at a time, and `AUTH_CUSTOM_NAME` must match `^[a-z0-9][a-z0-9_-]*$`. + ### Security Considerations for auth.send-jwt-header When `auth.send-jwt-header=true` is enabled: