scribase-mail-studio/.env.selfhost.example
caelum0x 2e3d92594b fix(verification): auto-demote Reacher to lite fallback when SMTP self-test fails
isConfigured() only checked that REACHER_ENABLED/REACHER_API_URL were set,
never that Reacher could actually complete a real SMTP check. On a host
where outbound TCP 25 is blocked (e.g. Oracle Cloud default), a configured
Reacher backend returns 200 is_reachable:"unknown" for every address
forever, and checkOne() labeled that method:"reacher_smtp" as if it were
authoritative -- silently losing the disposable-domain/syntax/MX coverage
liteCheck() already provides for free.

Add ensureReacherHealthy(): a cached, periodically-refreshed self-test that
probes a made-up mailbox at a real, non-catch-all provider
(REACHER_SELFTEST_EMAIL, default gmail.com). A healthy Reacher must return a
determinate verdict (e.g. "invalid") for that probe since the mailbox
doesn't exist; a structurally broken one can only ever return "unknown".
checkAddresses() now demotes to liteCheck() whenever the probe fails,
logging a clear warning (not a silent downgrade), and logs a recovery
notice once a later probe succeeds again.

9 new unit tests cover the healthy-probe path, the demoted-fallback path,
probe caching (no fetch spam), and recovery after a simulated TTL window.
Full suite re-verified: unit 665/665, trpc 43/43, api 144/144, tsc clean.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-11-04 16:30:51 +03:00

109 lines
4.3 KiB
Plaintext

# ---------------------------------------------------------------------------
# Scribase Mail - self-host configuration (used by compose.yml)
# ./scripts/selfhost.sh copies this file to .env and fills in the secrets.
# ---------------------------------------------------------------------------
# Optional services to start. "mailpit" catches all mail at
# http://localhost:8025 for local trials; remove it once SMTP_* below points
# at a real relay.
COMPOSE_PROFILES="mailpit"
# Public URL of the app (also used for tracking and unsubscribe links)
NEXTAUTH_URL="http://localhost:3000"
# Random secret: openssl rand -hex 32
NEXTAUTH_SECRET="__GENERATE__"
# Postgres (compose builds DATABASE_URL from these)
POSTGRES_USER="scribase_mail"
POSTGRES_PASSWORD="__GENERATE__"
POSTGRES_DB="scribase_mail"
# Address for sign-in codes and notifications
FROM_EMAIL="Scribase Mail <noreply@scribase-mail.localhost>"
# Admin user (sees Admin > Email provider)
ADMIN_EMAIL="admin@scribase-mail.localhost"
# ---------------------------------------------------------------------------
# Sending provider
# smtp = any SMTP relay (Postfix, Mailpit, a hosted SMTP service). DKIM is
# signed by Scribase Mail with a per-domain key; domains verify by DNS
# (a DKIM TXT record and an SPF TXT record).
# oci = Oracle Cloud Email Delivery (managed DKIM, suppression list and
# delivery logs). Fill in the OCI section below.
# ---------------------------------------------------------------------------
EMAIL_PROVIDER="smtp"
SMTP_HOST="mailpit"
SMTP_PORT="1025"
SMTP_USER=""
SMTP_PASS=""
# "true" for implicit TLS (port 465). Defaults to true only on port 465.
# SMTP_SECURE="false"
# Require STARTTLS on 587/25 (recommended for real relays)
# SMTP_REQUIRE_TLS="true"
# SPF value shown to users for their sending domains
# SMTP_SPF_RECORD="v=spf1 a mx include:your-relay.example ~all"
## Oracle Cloud Email Delivery (EMAIL_PROVIDER="oci")
# SMTP_HOST="smtp.email.eu-frankfurt-1.oci.oraclecloud.com"
# SMTP_PORT="587"
# SMTP_USER="<oci-smtp-credential-username>"
# SMTP_PASS="<oci-smtp-credential-password>"
# OCI_REGION="eu-frankfurt-1"
# OCI_TENANCY="ocid1.tenancy.oc1..<...>"
# OCI_USER="ocid1.user.oc1..<...>"
# OCI_FINGERPRINT="<api-key-fingerprint>"
# PEM contents with \n escapes (or mount the key and set OCI_PRIVATE_KEY_PATH)
# OCI_PRIVATE_KEY=""
# OCI_COMPARTMENT_ID="ocid1.compartment.oc1..<...>" # defaults to the tenancy
# SUPPRESSION_POLL_CRON="*/5 * * * *"
# DELIVERY_LOG_POLL_CRON="* * * * *"
# OCI_LOG_GROUP_NAME="scribase-mail"
## Optional OAuth login
# GITHUB_ID=""
# GITHUB_SECRET=""
# GOOGLE_CLIENT_ID=""
# GOOGLE_CLIENT_SECRET=""
## Shown to customers on the SMTP settings page (apps/smtp-server)
# SMTP_PUBLIC_HOST="smtp.mail.example.com"
# SMTP_PUBLIC_USER="scribase"
## Content screening of outgoing mail (on by default). An empty value turns
## the public phishing feed off (useful offline).
# CONTENT_SCREENING_ENABLED="true"
# SCREENING_FEED_URLS=""
API_RATE_LIMIT=10
AUTH_EMAIL_RATE_LIMIT=5
## Webhook URLs must resolve to public IPs (SSRF guard); list internal
## hostnames to exempt, comma separated.
# WEBHOOK_ALLOWED_PRIVATE_HOSTS=""
## Optional: clear stored email content after this many days
# EMAIL_CLEANUP_DAYS=30
## Pre-send address verification (reacherhq/check-if-email-exists, MIT
## licensed, self-hosted). Checks each recipient's deliverability before a
## send reaches the relay, so bounces never spend a send credit. Disabled
## (no-op, fails open) unless REACHER_API_URL is set. Run the sidecar with
## `docker compose --profile reacher up -d` (see compose.yml) or any
## reacherhq/backend container you already run.
# REACHER_API_URL="http://reacher:8080"
# REACHER_API_KEY=""
# REACHER_TIMEOUT_MS=4000
# REACHER_BLOCK_VERDICTS="invalid"
## A periodic self-test probes this address; if Reacher can't actually
## complete an SMTP check (e.g. outbound TCP 25 is blocked), checks
## auto-demote to the syntax+MX+disposable fallback with a logged warning
## instead of silently mislabeling degraded results as "reacher_smtp".
# REACHER_SELFTEST_EMAIL="reacher-selftest-probe-does-not-exist@gmail.com"
## Ports and image (compose)
# SCRIBASE_MAIL_BIND="127.0.0.1" # 0.0.0.0 to expose without a reverse proxy
# SCRIBASE_MAIL_PORT="3000"
# MAILPIT_PORT="8025"
# SCRIBASE_MAIL_IMAGE="ghcr.io/caelum0x/scribase-mail-studio:latest"