diff options
| -rw-r--r-- | contrib/webmentions-ssg.example.cfg | 175 | ||||
| -rw-r--r-- | webmentions_ssg/config.py | 82 |
2 files changed, 140 insertions, 117 deletions
diff --git a/contrib/webmentions-ssg.example.cfg b/contrib/webmentions-ssg.example.cfg index 33f43af..8dd347b 100644 --- a/contrib/webmentions-ssg.example.cfg +++ b/contrib/webmentions-ssg.example.cfg @@ -8,14 +8,14 @@ import logging # --------------------------------------------------------------------------- -# Flask / Application +# Application # --------------------------------------------------------------------------- DEBUG = False BOOTSTRAP_SERVE_LOCAL = True # BOOTSTRAP_BOOTSWATCH_THEME = "Materia" # --------------------------------------------------------------------------- -# Flask / Security +# Security and reverse proxy # --------------------------------------------------------------------------- # Generate a persistent random key, e.g.: # python -c 'import secrets; print(secrets.token_urlsafe(32))' @@ -23,25 +23,26 @@ BOOTSTRAP_SERVE_LOCAL = True # Production refuses to start without a real, persistent key (>=32 random bytes); # set the same SECRET_KEY in the web process and every worker. # Changing this key invalidates all existing signed login sessions. -# Upgrading to password-bound sessions also requires users to sign in again once. SECRET_KEY = "REPLACE_WITH_A_LONG_RANDOM_SECRET" -# When deployed behind a trusted reverse proxy, set this to the EXACT number -# of trusted hops that set X-Forwarded-For and X-Forwarded-Proto. Use 1 for a +# When deployed behind a trusted reverse proxy, set this to the EXACT number of +# trusted hops that set X-Forwarded-For and X-Forwarded-Proto. Use 1 for a # single nginx instance directly in front of the application; 0 (default) # ignores forwarded headers. Do not enable this if the backend is reachable # directly or if the proxy fails to overwrite untrusted forwarded headers. -# See README.md for an nginx example and multi-proxy caveats. PROXY_FIX_TRUSTED_HOPS = 0 # --------------------------------------------------------------------------- -# Database and logging +# Database # --------------------------------------------------------------------------- # SQLite with an absolute file path (four slashes after sqlite:). # Ensure the service user can write to this directory. SQLALCHEMY_DATABASE_URI = "sqlite:////var/lib/webmentions-ssg/webmentions-ssg.db" SQLALCHEMY_TRACK_MODIFICATIONS = False +# --------------------------------------------------------------------------- +# Logging +# --------------------------------------------------------------------------- # Ensure the service user can write to the log file / directory. LOG_FILE = "/var/log/webmentions-ssg.log" LOG_LEVEL = logging.INFO @@ -50,34 +51,57 @@ LOG_FILE_MAX_BYTES = 20_000_000 LOG_FILE_BACKUP_COUNT = 10 # --------------------------------------------------------------------------- -# Receiving Webmentions +# Background tasks (Huey) # --------------------------------------------------------------------------- -# Required: exact hostnames permitted in the 'target' field of an incoming -# Webmention. Include each hostname you serve; wildcards are not supported. -ALLOWED_TARGET_HOSTNAMES = {"example.com", "www.example.com"} - -# Maximum size of an incoming HTTP request body, including form encoding. -# This global Flask limit also applies to login and administration routes. -MAX_CONTENT_LENGTH = 64 * 1024 -# Independent UTF-8 byte limit for each URL submitted to /endpoint. -# Increase cautiously: a longer URL consumes additional storage and network IO. -MAX_WEBMENTION_URL_BYTES = 8192 -# Delete failed/deleted received Webmentions this many days after their most -# recent update; verified, pending, and outgoing records are never purged. -# Deleted status pages return 404; the same pair can be resubmitted afterward. -RECEIVED_RETENTION_DAYS = 30 -# Daily at 03:00 UTC (Huey's default timezone). -RECEIVED_RETENTION_SCHEDULE = "0 3 * * *" +# Use a shared, persistent backend for production app and worker processes. +# Huey messages and results use a restricted JSON serializer; do not configure +# a pickle serializer in either process. Keep both on the same app version. +# +# SECURITY: Only the web app and trusted worker should be able to write to the +# broker. Redis should bind to loopback or a private network, with protected +# mode, firewall rules, authentication/dedicated ACLs and TLS when remote. Do +# not expose Redis to public networks or untrusted tenants: even without +# pickle, an attacker who can write jobs can invoke registered tasks. For +# file/SQLite backends, restrict directory and database permissions to the +# app/worker account. For Postgres, use a dedicated least-privilege role and +# private/ACL-restricted network access. +# +# Production startup refuses the implicit memory:// fallback, as well as +# blackhole://, since neither can reliably deliver work to a separate process. +# File and SQLite backends follow SQLAlchemy's path convention, not RFC 8089: +# three slashes for relative paths, four for absolute paths. +# HUEY_URL = "file:///huey-queue" # Relative: ./huey-queue +# HUEY_URL = "file:////var/lib/webmentions-ssg/huey-queue" # Absolute +# HUEY_URL = "sqlite:////var/lib/webmentions-ssg/huey.db" # Absolute +HUEY_URL = "redis://127.0.0.1:6379/0" +# --------------------------------------------------------------------------- +# Outbound HTTP requests (shared by receiver and sender) +# --------------------------------------------------------------------------- # Defense in depth: restrict the Huey worker service account with outbound # firewall/network-policy rules that block loopback, RFC1918, link-local, ULA, # and cloud metadata ranges, including IPv6. The application also pins # validated DNS IPs, but deployment-level filtering is still necessary. -# Limits for fetching/verifying incoming sources. +# Limits for verifying sources and delivering Webmentions. REQUEST_TIMEOUT_SECONDS = 5.0 # seconds per socket operation (both directions) REQUEST_TOTAL_TIMEOUT_SECONDS = 30.0 # seconds overall, including DNS, redirects and body MAX_REDIRECTS = 20 # also used for outgoing requests + +# --------------------------------------------------------------------------- +# Receiver +# --------------------------------------------------------------------------- +# Required: exact hostnames permitted in the 'target' field of an incoming +# Webmention. Include each hostname you serve; wildcards are not supported. +ALLOWED_TARGET_HOSTNAMES = {"example.com", "www.example.com"} + +# Maximum size of an incoming HTTP request body, including form encoding. This +# global Flask limit also applies to login and administration routes. +MAX_CONTENT_LENGTH = 64 * 1024 +# Independent UTF-8 byte limit for each URL submitted to /endpoint. +# Increase cautiously: a longer URL consumes additional storage and network IO. +MAX_WEBMENTION_URL_BYTES = 8192 +# Maximum response body size for fetching an incoming source. MAX_RECEIVED_SOURCE_BYTES = 1_000_000 # Requeue stuck verifications and lost queued tasks after 15 minutes. VERIFICATION_STALE_AFTER_SECONDS = 900 @@ -87,6 +111,41 @@ VERIFICATION_MAX_RECOVERIES = 3 # Huey cron expression: every five minutes (in UTC). VERIFICATION_RECOVERY_SCHEDULE = "*/5 * * * *" +# Delete failed/deleted received Webmentions this many days after their most +# recent update; verified, pending, and outgoing records are never purged. +# Deleted status pages return 404; the same pair can be resubmitted afterward. +RECEIVED_RETENTION_DAYS = 30 +# Daily at 03:00 UTC (Huey's default timezone). +RECEIVED_RETENTION_SCHEDULE = "0 3 * * *" + +# --------------------------------------------------------------------------- +# Scanner +# --------------------------------------------------------------------------- +# Folder containing generated pages named index.html. Set to None to disable +# scanning. Its root-level index.html is not scanned. +SITE_OUTPUT_DIRECTORY = "/var/www/example.com/public" + +# Needed for pages without absolute canonical URLs. +SITE_BASE_URL = "https://example.com/" + +# Huey cron expression: minute hour day-of-month month day-of-week. +SOURCE_SCAN_SCHEDULE = "0 * * * *" # every hour + +# --------------------------------------------------------------------------- +# Sender +# --------------------------------------------------------------------------- +# Do not send Webmentions to your own site. Glob patterns are supported here. +IGNORED_TARGET_HOSTNAMES = ("example.com", "*.example.com") +MAX_DISCOVERY_TARGET_BYTES = 1_000_000 + +# Temporary delivery failures use persisted exponential backoff: 1, 2, 4, 8, +# then 16 hours between attempts with these defaults. After six total attempts +# for a revision, the failure becomes terminal. A changed source or explicit +# manual resend starts a fresh retry budget. +SEND_MAX_ATTEMPTS = 6 +SEND_RETRY_BASE_SECONDS = 3600 +SEND_RETRY_MAX_SECONDS = 86400 + # --------------------------------------------------------------------------- # Rate limiting # --------------------------------------------------------------------------- @@ -109,76 +168,24 @@ ENDPOINT_GLOBAL_RATE_LIMIT = "1000/hour" ENDPOINT_REVERIFY_COOLDOWN_SECONDS = 600 # Limit login POST attempts per client IP, and separately for each submitted -# username across IPs (case-folded and hashed before being used as a key). -# Both limits apply to POSTs, even unsuccessful validation attempts. A per-user +# username across IPs (case-folded and hashed before being used as a key). Both +# limits apply to POSTs, even unsuccessful validation attempts. A per-user # bucket can be deliberately exhausted to temporarily deny that account login; # keep its allowance higher than the per-IP limit and monitor for abuse. LOGIN_RATE_LIMIT = "5/minute;30/hour" LOGIN_USERNAME_RATE_LIMIT = "20/minute;100/hour" # --------------------------------------------------------------------------- -# Sending Webmentions from a statically generated site +# Email digest # --------------------------------------------------------------------------- -# Folder containing generated pages named index.html. Set to None to disable -# scanning. Its root-level index.html is not scanned. -SITE_OUTPUT_DIRECTORY = "/var/www/example.com/public" - -# Needed for pages without absolute canonical URLs. -SITE_BASE_URL = "https://example.com/" - -# Huey cron expression: minute hour day-of-month month day-of-week. -SOURCE_SCAN_SCHEDULE = "0 * * * *" # every hour - -# Temporary delivery failures use persisted exponential backoff: 1, 2, 4, -# 8, then 16 hours between attempts with these defaults. After six total -# attempts for a revision, the failure becomes terminal. A changed source or -# explicit manual resend starts a fresh retry budget. -SEND_MAX_ATTEMPTS = 6 -SEND_RETRY_BASE_SECONDS = 3600 -SEND_RETRY_MAX_SECONDS = 86400 - -# Do not send Webmentions to your own site. Glob patterns are supported here. -IGNORED_TARGET_HOSTNAMES = ("example.com", "*.example.com") -MAX_DISCOVERY_TARGET_BYTES = 1_000_000 - -# --------------------------------------------------------------------------- -# Background tasks (Huey) -# --------------------------------------------------------------------------- -# Use a shared, persistent backend for production app and worker processes. -# Huey messages and results use a restricted JSON serializer; do not configure -# a pickle serializer in either process. Keep both on the same app version. -# -# SECURITY: Only the web app and trusted worker should be able to write to the -# broker. Redis should bind to loopback or a private network, with protected -# mode, firewall rules, authentication/dedicated ACLs and TLS when remote. -# Do not expose Redis to public networks or untrusted tenants: even without -# pickle, an attacker who can write jobs can invoke registered tasks. -# For file/SQLite backends, restrict directory and database permissions to -# the app/worker account. For Postgres, use a dedicated least-privilege role -# and private/ACL-restricted network access. -# -# MIGRATION FROM PICKLE: Drain outstanding jobs on the old trusted deployment -# first, stop all producers and workers, and clear or migrate old queue, -# scheduled-task and result data before restarting *both* with JSON. -# Old pickle payloads cannot be read by the new serializer. Do not deserialize -# legacy data from any backend that untrusted parties could have modified. -# Production startup refuses the implicit memory:// fallback, as well as -# blackhole://, since neither can reliably deliver work to a separate process. -# File and SQLite backends follow SQLAlchemy's path convention, not RFC 8089: -# three slashes for relative paths, four for absolute paths. -# HUEY_URL = "file:///huey-queue" # Relative: ./huey-queue -# HUEY_URL = "file:////var/lib/webmentions-ssg/huey-queue" # Absolute -# HUEY_URL = "sqlite:////var/lib/webmentions-ssg/huey.db" # Absolute -HUEY_URL = "redis://127.0.0.1:6379/0" - -# --------------------------------------------------------------------------- -# Email notifications for newly verified received Webmentions -# --------------------------------------------------------------------------- -# Set DIGEST_EMAIL = None to disable notification emails. +# Set DIGEST_EMAIL = None to disable notification digest emails. DIGEST_EMAIL = "admin@example.com" # Daily notification digest at 08:00 UTC (Huey defaults to UTC). DIGEST_SCHEDULE = "0 8 * * *" +# --------------------------------------------------------------------------- +# Mail (SMTP) +# --------------------------------------------------------------------------- # Example SMTP-over-STARTTLS setup; adapt to your mail provider. MAIL_SERVER = "smtp.example.com" MAIL_PORT = 587 diff --git a/webmentions_ssg/config.py b/webmentions_ssg/config.py index 15667ab..2110a62 100644 --- a/webmentions_ssg/config.py +++ b/webmentions_ssg/config.py @@ -13,56 +13,87 @@ MIN_SECRET_KEY_LENGTH = 32 class DefaultConfig: + # Application TESTING = False DEBUG = False - # Production must provide a persistent, random key through configuration. - SECRET_KEY = None BOOTSTRAP_SERVE_LOCAL = True # BOOTSTRAP_BOOTSWATCH_THEME = "Materia" + + # Security and reverse proxy + # Production must provide a persistent, random key through configuration. + SECRET_KEY = None # Secure by default; deployment configuration can override these values. SESSION_COOKIE_SECURE = True SESSION_COOKIE_HTTPONLY = True SESSION_COOKIE_SAMESITE = "Lax" + # Number of trusted reverse-proxy hops for X-Forwarded-For/Proto. + # 0 (default) means forwarded headers are not trusted. + PROXY_FIX_TRUSTED_HOPS = 0 + + # Database + SQLALCHEMY_DATABASE_URI = "sqlite:///webmentions-ssg.db" + + # Logging LOG_FILE = "/var/log/webmentions-ssg.log" - LOG_FORMAT = "[%(asctime)s]:%(levelname)s:%(name)s %(message)s" LOG_LEVEL = logging.INFO + LOG_FORMAT = "[%(asctime)s]:%(levelname)s:%(name)s %(message)s" LOG_FILE_MAX_BYTES = 20_000_000 LOG_FILE_BACKUP_COUNT = 10 - SQLALCHEMY_DATABASE_URI = "sqlite:///webmentions-ssg.db" + # Background tasks (Huey) + # HUEY_URL is intentionally unset; production must configure a persistent queue. + + # Outbound HTTP requests (shared by receiver and sender) + REQUEST_TIMEOUT_SECONDS = 5.0 + # Absolute wall-clock budget for each verification or delivery attempt. + REQUEST_TOTAL_TIMEOUT_SECONDS = 30.0 + MAX_REDIRECTS = 20 + + # Receiver # Empty by default: no target hostnames are accepted until configured. ALLOWED_TARGET_HOSTNAMES = frozenset() # Cap incoming HTTP request bodies (also applies to other Flask routes). MAX_CONTENT_LENGTH = 64 * 1024 # Independent UTF-8 byte limit for each submitted source/target URL. MAX_WEBMENTION_URL_BYTES = 8192 - # Purge terminal failed/source-removed received Webmentions after 30 days. - RECEIVED_RETENTION_DAYS = 30 - RECEIVED_RETENTION_SCHEDULE = "0 3 * * *" - MAX_REDIRECTS = 20 MAX_RECEIVED_SOURCE_BYTES = 1_000_000 - MAX_DISCOVERY_TARGET_BYTES = 1_000_000 - REQUEST_TIMEOUT_SECONDS = 5.0 - # Absolute wall-clock budget for each verification or delivery attempt. - REQUEST_TOTAL_TIMEOUT_SECONDS = 30.0 # Requeue abandoned verification attempts after 15 minutes. VERIFICATION_STALE_AFTER_SECONDS = 900 # Maximum automatic recoveries of a stale received/verifying row. VERIFICATION_MAX_RECOVERIES = 3 VERIFICATION_RECOVERY_SCHEDULE = "*/5 * * * *" + # Purge terminal failed/source-removed received Webmentions after 30 days. + RECEIVED_RETENTION_DAYS = 30 + RECEIVED_RETENTION_SCHEDULE = "0 3 * * *" + # Scanner SITE_OUTPUT_DIRECTORY = None SITE_BASE_URL = None - IGNORED_TARGET_HOSTNAMES = () SOURCE_SCAN_SCHEDULE = "0 * * * *" + + # Sender + IGNORED_TARGET_HOSTNAMES = () + MAX_DISCOVERY_TARGET_BYTES = 1_000_000 # Total send attempts per source revision (not additional retries). SEND_MAX_ATTEMPTS = 6 SEND_RETRY_BASE_SECONDS = 3600 SEND_RETRY_MAX_SECONDS = 86400 + # Rate limiting + RATELIMIT_STORAGE_URI = "memory://" + RATELIMIT_HEADERS_ENABLED = True + ENDPOINT_RATE_LIMIT = "10/minute;100/hour" + ENDPOINT_GLOBAL_RATE_LIMIT = "1000/hour" + ENDPOINT_REVERIFY_COOLDOWN_SECONDS = 600 + LOGIN_RATE_LIMIT = "5/minute;30/hour" + # Separate cross-IP limit for each submitted username (hashed in storage). + LOGIN_USERNAME_RATE_LIMIT = "20/minute;100/hour" + + # Email notifications DIGEST_EMAIL = None DIGEST_SCHEDULE = "0 8 * * *" + # Mail (SMTP) MAIL_SERVER = "localhost" MAIL_PORT = 25 MAIL_USE_TLS = False @@ -71,21 +102,6 @@ class DefaultConfig: MAIL_PASSWORD = None MAIL_DEFAULT_SENDER = None - # Number of trusted reverse-proxy hops for X-Forwarded-For/Proto. - # 0 (default) means forwarded headers are not trusted. - PROXY_FIX_TRUSTED_HOPS = 0 - - RATELIMIT_STORAGE_URI = "memory://" - RATELIMIT_HEADERS_ENABLED = True - - ENDPOINT_RATE_LIMIT = "10/minute;100/hour" - ENDPOINT_GLOBAL_RATE_LIMIT = "1000/hour" - ENDPOINT_REVERIFY_COOLDOWN_SECONDS = 600 - - LOGIN_RATE_LIMIT = "5/minute;30/hour" - # Separate cross-IP limit for each submitted username (hashed in storage). - LOGIN_USERNAME_RATE_LIMIT = "20/minute;100/hour" - class DevelopmentConfig(DefaultConfig): DEBUG = True @@ -103,17 +119,17 @@ class ProductionConfig(DefaultConfig): class TestingConfig(DefaultConfig): TESTING = True - SESSION_COOKIE_SECURE = False - - SECRET_KEY = "testing-secret-key" WTF_CSRF_ENABLED = False - LOG_FILE = "testing/webmentions-ssg-tests.log" - LOG_LEVEL = logging.DEBUG + SECRET_KEY = "testing-secret-key" + SESSION_COOKIE_SECURE = False SQLALCHEMY_DATABASE_URI = "sqlite:///:memory:" SQLALCHEMY_TRACK_MODIFICATIONS = False + LOG_FILE = "testing/webmentions-ssg-tests.log" + LOG_LEVEL = logging.DEBUG + HUEY_URL = "memory://" ALLOWED_TARGET_HOSTNAMES = frozenset({"dennisfink.me"}) |
