fix: parameter docs + --help text inconsistencies (audit) (#2077)
* 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.
This commit is contained in:
Dmitry Verkhoturov
@@ -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"`
|
||||
}
|
||||
|
||||
@@ -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"<john.doe@example.com>`) |
|
||||
@@ -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:
|
||||
|
||||
Reference in New Issue
Block a user