umbermark-cli 1.0.0rc1__py3-none-any.whl

umbermark/core/settings.py

@@ -0,0 +1,238 @@
+"""Runtime settings loaded from environment.
+
+Required env vars (no defaults — caller must set):
+    SECRET_KEY        — used by itsdangerous for magic links + session signing
+    KEY_PEPPER        — used by keyenc for saved-server key encryption
+    IP_PEPPER         — used by crypto.hash_with_pepper for ip_hash
+    TARGET_PEPPER     — used by crypto.hash_with_pepper for target_host_hash
+    DATABASE_PATH     — sqlite file path
+    REDIS_URL         — redis://host:port/db or fakeredis://...
+    BASE_URL          — canonical https URL for the deployment
+
+Optional env vars (with defaults shown):
+    SESSION_TTL_SECONDS                — default 2_592_000 (30 days)
+    ANONYMOUS_REPORT_TTL_SECONDS       — default 2_592_000 (30 days)
+    POSTMARK_WIRED / TURNSTILE_WIRED   — default 0 (wired: false, C3). While 0 the Postmark and Turnstile
+                                         settings below are IGNORED: no email provider, no captcha, no
+                                         Cloudflare origin in the CSP. Polar is the only payment processor.
+    POSTMARK_TOKEN                     — only when POSTMARK_WIRED=1: real-mode email transport
+    POLAR_API_TOKEN                    — if set, real-mode Polar client
+    POLAR_WEBHOOK_SECRET               — HMAC-SHA256 secret for /billing/webhook
+    POLAR_PRODUCT_ONESHOT              — Polar product id for $5 one-shot
+    POLAR_PRODUCT_SOLO                 — Polar product id for $9/mo Solo tier
+    POLAR_PRODUCT_PRO                  — Polar product id for $19/mo Pro tier
+    POLAR_PRODUCT_AGENCY               — Polar product id for $49/mo Agency tier
+    POLAR_API_BASE                     — Polar API base URL; default https://api.polar.sh/v1
+                                         (sandbox: https://sandbox-api.polar.sh/v1)
+    UPLOAD_RATE_LIMIT_PER_HOUR         — max POST /scan/upload per IP per hour; default 20
+    FREE_PUSH_LIMIT_PER_DAY            — max POST /api/push per free-tier user per rolling 24h; default 20 (paid tiers uncapped)
+    PDF_STORAGE_DIR                    — on-disk PDF cache directory
+    TURNSTILE_SECRET                   — only when TURNSTILE_WIRED=1: Cloudflare Turnstile siteverify secret
+    TURNSTILE_SITE_KEY                 — only when TURNSTILE_WIRED=1: public site key embedded in widget
+    OPERATOR_EMAIL                     — recipient for operator daily abuse digest
+    EMAIL_FROM                         — outbound from-address; default noreply@<base_url host>
+    EMAIL_REPLY_TO                     — optional single address sent as Postmark ReplyTo on every message
+    SIGNIN_ENABLED                     — default 0. While 0 every sign-in / magic-link / CLI-login /
+                                         claim route answers 403, sessions and API tokens are not
+                                         honoured, and all existing sessions are revoked at boot.
+                                         The quad42 gate flips this once Starhold Account exists.
+    STARSHIP_ENABLED                   — default 0 (STAR-227). While 0 nothing from umbermark.starship is mounted and
+                                         behaviour is unchanged. See umbermark/starship/config.py for the STARSHIP_* settings.
+    MONTHLY_PLANS_ENABLED              — default 0. While 0 the Solo/Pro/Agency plans are hidden everywhere,
+                                         /billing/upgrade refuses, and subscription webhooks are ignored.
+
+  External-scan network path (UMBR-65; all unset = old behaviour):
+    SCAN_RESOLVERS                     — comma list of recursive DNS servers (UDP) used to resolve scan targets
+                                         and DNS-TXT proofs, so a name the host maps locally (its own hostname ->
+                                         127.0.1.1) resolves as the internet sees it. Unset = system resolver
+                                         for targets, 1.1.1.1/8.8.8.8 for TXT.
+    SCANNER_SELF_IPS                   — comma list of this server's own public IPs.
+    SCANNER_HAIRPIN_ADDR               — address that reaches this server from inside the container (rootless
+                                         podman/pasta: 169.254.1.2). With SCANNER_SELF_IPS set, probes of a self IP
+                                         go here, because pasta keeps the host's own IP inside the namespace.
+    SCANNER_SELF_PUBLIC_PORTS          — default 80,443: the only ports of this server reachable from the
+                                         internet. Other ports on a self IP read as filtered, as from outside.
+"""
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Mapping
+
+# Single source of truth for the anonymous report link lifetime (30 days).
+DEFAULT_ANONYMOUS_REPORT_TTL_SECONDS = 2_592_000
+
+# Default sign-in session lifetime (30 days); the privacy page quotes it.
+DEFAULT_SESSION_TTL_SECONDS = 2_592_000
+
+_REQUIRED = (
+    "SECRET_KEY",
+    "KEY_PEPPER",
+    "IP_PEPPER",
+    "TARGET_PEPPER",
+    "DATABASE_PATH",
+    "REDIS_URL",
+    "BASE_URL",
+)
+
+
+_ADDR_RE = re.compile(r"^[^\s<>,;:\"()@]+@[^\s<>,;:\"()@]+\.[^\s<>,;:\"()@]+$")
+
+
+def _reply_to(value: str | None, name: str = "EMAIL_REPLY_TO") -> str | None:
+    """Optional Reply-To: one plain address (no display name, no list). Unset or blank = None."""
+    v = (value or "").strip()
+    if not v:
+        return None
+    if not _ADDR_RE.match(v):
+        raise ValueError(f"{name} must be a single plain email address")
+    return v
+
+
+def _flag(raw: str | None) -> bool:
+    """Parse a 0/1 style env switch. Unset or anything unrecognised is OFF."""
+    return (raw or "0").strip().lower() in ("1", "true", "yes", "on")
+
+
+def _csv(raw: str | None) -> tuple[str, ...]:
+    """Comma list -> tuple of non-empty, stripped items."""
+    return tuple(p.strip() for p in (raw or "").split(",") if p.strip())
+
+
+@dataclass(frozen=True, slots=True)
+class Settings:
+    secret_key: str
+    key_pepper: str
+    ip_pepper: str
+    target_pepper: str
+    database_path: Path
+    redis_url: str
+    base_url: str
+    session_ttl_seconds: int = DEFAULT_SESSION_TTL_SECONDS
+    anonymous_report_ttl_seconds: int = DEFAULT_ANONYMOUS_REPORT_TTL_SECONDS
+    upload_rate_limit_per_hour: int = 20
+    free_push_limit_per_day: int = 20
+    postmark_token: str | None = None
+    polar_api_token: str | None = None
+    polar_webhook_secret: str | None = None
+    polar_product_oneshot: str | None = None
+    polar_product_solo: str | None = None
+    polar_product_pro: str | None = None
+    polar_product_agency: str | None = None
+    polar_api_base: str = "https://api.polar.sh/v1"
+    pdf_storage_dir: Path | None = None
+    turnstile_secret: str | None = None
+    turnstile_site_key: str | None = None
+    operator_email: str | None = None
+    email_from: str | None = None
+    email_reply_to: str | None = None
+    # Pause switch: CHECKOUT_PAUSED=1 makes every Polar checkout route 503.
+    checkout_paused: bool = False
+    # Sign-in switch (STAR-147 / Q43). Closed by default: nobody can sign in
+    # until the Starhold Account launches and the gate flips SIGNIN_ENABLED=1.
+    signin_enabled: bool = False
+    # Monthly plans (Solo/Pro/Agency) are hidden and un-purchasable while 0
+    # (Q42/Q44). MONTHLY_PLANS_ENABLED=1 restores the old behaviour for the gate.
+    monthly_plans_enabled: bool = False
+    # C3: third-party providers that are NOT connected. Their credentials are
+    # ignored unless the matching *_WIRED switch is on.
+    postmark_wired: bool = False
+    turnstile_wired: bool = False
+    # STAR-227: Starhold Account integration. Off by default; `starship` is None unless enabled.
+    starship_enabled: bool = False
+    starship: object | None = None
+    # UMBR-65: how external scans reach targets (see module docstring).
+    scan_resolvers: tuple[str, ...] = ()
+    scanner_self_ips: tuple[str, ...] = ()
+    scanner_hairpin_addr: str = ""
+    scanner_self_public_ports: tuple[int, ...] = (80, 443)
+
+    def apply_scan_network(self) -> None:
+        """Install the external-scan network path in this process (web + worker)."""
+        from umbermark.core.external import ownership
+
+        ownership.configure_network(
+            resolvers=self.scan_resolvers,
+            self_ips=self.scanner_self_ips,
+            hairpin_addr=self.scanner_hairpin_addr,
+            self_public_ports=self.scanner_self_public_ports,
+        )
+
+    @property
+    def billing_enabled(self) -> bool:
+        """True only when a real Polar client can be built (token + one-shot product + webhook secret).
+
+        When False the app must not offer purchase/upgrade surfaces: main.py
+        falls back to FakePolarClient, which hands strangers a fake checkout.
+        """
+        # The webhook secret is required too: without it every paid webhook
+        # fails signature checks (401) and buyers pay but are never granted.
+        return bool(
+            self.polar_api_token
+            and self.polar_product_oneshot
+            and self.polar_webhook_secret
+        )
+
+    @property
+    def email_enabled(self) -> bool:
+        """True only when a real transactional email provider is configured.
+
+        Without it, magic-link sign-in mail goes to the console and never arrives.
+        """
+        return bool(self.postmark_token)
+
+    @classmethod
+    def from_env(cls, env: Mapping[str, str] | None = None) -> "Settings":
+        e = env if env is not None else os.environ
+        missing = [name for name in _REQUIRED if not e.get(name)]
+        if missing:
+            raise ValueError(f"Missing required env vars: {', '.join(missing)}")
+        pdf_dir = e.get("PDF_STORAGE_DIR")
+        starship_on = _flag(e.get("STARSHIP_ENABLED"))
+        starship_cfg = None
+        if starship_on:
+            from umbermark.starship.config import StarshipConfig
+
+            starship_cfg = StarshipConfig.from_env(e, database_path=Path(e["DATABASE_PATH"]))
+        return cls(
+            secret_key=e["SECRET_KEY"],
+            key_pepper=e["KEY_PEPPER"],
+            ip_pepper=e["IP_PEPPER"],
+            target_pepper=e["TARGET_PEPPER"],
+            database_path=Path(e["DATABASE_PATH"]),
+            redis_url=e["REDIS_URL"],
+            base_url=e["BASE_URL"].rstrip("/"),
+            session_ttl_seconds=int(e.get("SESSION_TTL_SECONDS", DEFAULT_SESSION_TTL_SECONDS)),
+            anonymous_report_ttl_seconds=int(e.get("ANONYMOUS_REPORT_TTL_SECONDS", DEFAULT_ANONYMOUS_REPORT_TTL_SECONDS)),
+            upload_rate_limit_per_hour=int(e.get("UPLOAD_RATE_LIMIT_PER_HOUR") or 20),
+            free_push_limit_per_day=int(e.get("FREE_PUSH_LIMIT_PER_DAY") or 20),
+            postmark_token=(e.get("POSTMARK_TOKEN") or None) if _flag(e.get("POSTMARK_WIRED")) else None,
+            postmark_wired=_flag(e.get("POSTMARK_WIRED")),
+            turnstile_wired=_flag(e.get("TURNSTILE_WIRED")),
+            polar_api_token=e.get("POLAR_API_TOKEN") or None,
+            polar_webhook_secret=e.get("POLAR_WEBHOOK_SECRET") or None,
+            polar_product_oneshot=e.get("POLAR_PRODUCT_ONESHOT") or None,
+            polar_product_solo=e.get("POLAR_PRODUCT_SOLO") or None,
+            polar_product_pro=e.get("POLAR_PRODUCT_PRO") or None,
+            polar_product_agency=e.get("POLAR_PRODUCT_AGENCY") or None,
+            polar_api_base=e.get("POLAR_API_BASE") or "https://api.polar.sh/v1",
+            pdf_storage_dir=Path(pdf_dir) if pdf_dir else None,
+            turnstile_secret=(e.get("TURNSTILE_SECRET") or None) if _flag(e.get("TURNSTILE_WIRED")) else None,
+            turnstile_site_key=(e.get("TURNSTILE_SITE_KEY") or None) if _flag(e.get("TURNSTILE_WIRED")) else None,
+            operator_email=e.get("OPERATOR_EMAIL") or None,
+            email_from=e.get("EMAIL_FROM") or None,
+            email_reply_to=_reply_to(e.get("EMAIL_REPLY_TO")),
+            checkout_paused=_flag(e.get("CHECKOUT_PAUSED")),
+            signin_enabled=_flag(e.get("SIGNIN_ENABLED")),
+            monthly_plans_enabled=_flag(e.get("MONTHLY_PLANS_ENABLED")),
+            starship_enabled=starship_on,
+            starship=starship_cfg,
+            scan_resolvers=_csv(e.get("SCAN_RESOLVERS")),
+            scanner_self_ips=_csv(e.get("SCANNER_SELF_IPS")),
+            scanner_hairpin_addr=(e.get("SCANNER_HAIRPIN_ADDR") or "").strip(),
+            scanner_self_public_ports=tuple(
+                int(p) for p in (_csv(e.get("SCANNER_SELF_PUBLIC_PORTS")) or ("80", "443"))
+            ),
+        )

umbermark/core/short_id.py

@@ -0,0 +1,27 @@
+"""Unguessable report identifiers.
+
+A report URL is a capability: anyone holding it can read the report (shareable
+by design). So the id must be impossible to guess. 16 random bytes = 128 bits,
+rendered as 26 lowercase base32 characters [a-z2-7]. Ids from before STAR-147
+were 8 characters (40 bits); migration 012 retires them.
+"""
+from __future__ import annotations
+
+import base64
+import re
+import secrets
+
+ID_BYTES = 16  # 128 bits
+ID_LENGTH = 26  # base32 of 16 bytes, unpadded
+
+_FORMAT = re.compile(r"^[a-z2-7]{26}$")
+
+
+def generate() -> str:
+    """Return a 26-char [a-z2-7] id carrying 128 random bits."""
+    raw = base64.b32encode(secrets.token_bytes(ID_BYTES)).decode("ascii").lower()
+    return raw.rstrip("=")
+
+
+def is_current_format(short_id: str) -> bool:
+    return bool(_FORMAT.match(short_id or ""))

umbermark/core/signing.py

@@ -0,0 +1,24 @@
+"""Thin wrapper over `itsdangerous.URLSafeTimedSerializer`.
+
+Used for magic-link tokens and any other time-limited signed payload.
+The wrapper takes a `salt` parameter so different token kinds (login link
+vs. report claim vs. CLI device token) can't be cross-redeemed.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from itsdangerous import BadSignature, SignatureExpired, URLSafeTimedSerializer
+
+__all__ = ["sign_token", "verify_token", "BadSignature", "SignatureExpired"]
+
+
+def sign_token(payload: Any, secret_key: str, salt: str) -> str:
+    return URLSafeTimedSerializer(secret_key, salt=salt).dumps(payload)
+
+
+def verify_token(token: str, secret_key: str, salt: str, max_age_seconds: int) -> Any:
+    """Returns the original payload. Raises SignatureExpired or BadSignature."""
+    return URLSafeTimedSerializer(secret_key, salt=salt).loads(
+        token, max_age=max_age_seconds
+    )

umbermark/core/ssh.py

@@ -0,0 +1,156 @@
+"""Command-runner protocol + paramiko (real SSH), WSL (dogfood), fake (tests)."""
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass, field
+from typing import Protocol
+
+
+@dataclass
+class CommandResult:
+    stdout: str
+    stderr: str
+    exit_code: int
+
+    @property
+    def ok(self) -> bool:
+        return self.exit_code == 0
+
+
+class CommandRunner(Protocol):
+    def run(
+        self,
+        command: str,
+        sudo: bool = False,
+        timeout: float = 30.0,
+    ) -> CommandResult:
+        ...
+
+
+@dataclass
+class FakeRunner:
+    """Test double — programmable command-string -> CommandResult mapping.
+
+    A response registered under the bare command matches whether or not
+    `sudo=True` was passed, so tests don't have to mirror the runner's
+    sudo-prefixing convention.
+    """
+
+    responses: dict[str, CommandResult] = field(default_factory=dict)
+    calls: list[str] = field(default_factory=list)
+
+    def run(
+        self,
+        command: str,
+        sudo: bool = False,
+        timeout: float = 30.0,
+    ) -> CommandResult:
+        full_cmd = f"sudo -n {command}" if sudo else command
+        self.calls.append(full_cmd)
+        if command in self.responses:
+            return self.responses[command]
+        if full_cmd in self.responses:
+            return self.responses[full_cmd]
+        return CommandResult(
+            stdout="",
+            stderr=f"no fake response for: {command!r}",
+            exit_code=127,
+        )
+
+
+class ParamikoRunner:
+    """Real SSH runner via paramiko."""
+
+    def __init__(
+        self,
+        host: str,
+        user: str,
+        key_filename: str | None = None,
+        port: int = 22,
+        password: str | None = None,
+        connect_timeout: float = 10.0,
+    ) -> None:
+        import paramiko
+
+        self._client = paramiko.SSHClient()
+        self._client.set_missing_host_key_policy(paramiko.AutoAddPolicy())
+        connect_kwargs: dict = {
+            "hostname": host,
+            "username": user,
+            "port": port,
+            "timeout": connect_timeout,
+        }
+        if key_filename:
+            connect_kwargs["key_filename"] = key_filename
+        elif password:
+            connect_kwargs["password"] = password
+        self._client.connect(**connect_kwargs)
+
+    def run(
+        self,
+        command: str,
+        sudo: bool = False,
+        timeout: float = 30.0,
+    ) -> CommandResult:
+        full = f"sudo -n {command}" if sudo else command
+        _, stdout, stderr = self._client.exec_command(full, timeout=timeout)
+        out = stdout.read().decode("utf-8", errors="replace")
+        err = stderr.read().decode("utf-8", errors="replace")
+        rc = stdout.channel.recv_exit_status()
+        return CommandResult(stdout=out, stderr=err, exit_code=rc)
+
+    def close(self) -> None:
+        try:
+            self._client.close()
+        except Exception:
+            pass
+
+
+class WSLRunner:
+    """Run commands inside a WSL distro via `wsl.exe`. Local dogfood only —
+    not a substitute for SSH against real targets."""
+
+    def __init__(
+        self,
+        distro: str | None = None,
+        user: str | None = None,
+        wsl_exe: str = "wsl.exe",
+    ) -> None:
+        self.distro = distro
+        self.user = user
+        self.wsl_exe = wsl_exe
+
+    def _build_cmd(self, command: str, sudo: bool) -> list[str]:
+        cmd: list[str] = [self.wsl_exe]
+        if self.distro:
+            cmd += ["-d", self.distro]
+        if sudo:
+            cmd += ["--user", "root"]
+        elif self.user:
+            cmd += ["--user", self.user]
+        cmd += ["--", "bash", "-c", command]
+        return cmd
+
+    def run(
+        self,
+        command: str,
+        sudo: bool = False,
+        timeout: float = 30.0,
+    ) -> CommandResult:
+        try:
+            p = subprocess.run(
+                self._build_cmd(command, sudo),
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+                encoding="utf-8",
+                errors="replace",
+            )
+            return CommandResult(
+                stdout=p.stdout, stderr=p.stderr, exit_code=p.returncode
+            )
+        except subprocess.TimeoutExpired:
+            return CommandResult(stdout="", stderr="timeout", exit_code=124)
+
+    def close(self) -> None:  # parity with ParamikoRunner
+        return None

umbermark/core/ssh_fingerprint.py

@@ -0,0 +1,16 @@
+"""SHA-256 fingerprint of an SSH private key for audit logging.
+
+Per spec §17 — the audit log records a fingerprint so we can correlate
+repeat scan attempts by the same key without ever logging the private
+bytes themselves. The fingerprint is SHA-256 of the stripped UTF-8
+bytes of the PEM. Exact derivation does not need to match openssh's
+public-key fingerprint — only same-key→same-fingerprint and no leak.
+"""
+from __future__ import annotations
+
+import hashlib
+
+
+def derive_key_fingerprint(private_key_pem: str) -> str:
+    payload = private_key_pem.strip().encode("utf-8")
+    return hashlib.sha256(payload).hexdigest()

umbermark/core/tiers.py

@@ -0,0 +1,128 @@
+"""The one tier table (UMBR-19): what each plan allows. Every limit in Umbermark reads from here.
+
+Prices are display-only (what a buyer pays is set at Starship / the payment provider). Starship's catalog.yaml
+carries the same numbers for the three paid plans; tests/unit/test_tiers.py pins both to the operator-approved table.
+
+Limits
+  max_servers      saved servers the plan may hold (0 = none can be saved).
+  min_rescan_days  shortest allowed gap between scheduled re-scans (None = no scheduled re-scans at all).
+
+Enterprise is a contact-only plan sized by hand; it is not a tier here.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class Tier:
+    name: str
+    price_cents: int
+    max_servers: int
+    min_rescan_days: int | None
+
+    @property
+    def label(self) -> str:
+        return self.name.capitalize()
+
+
+TIERS: dict[str, Tier] = {
+    "free": Tier("free", 0, 0, None),
+    "solo": Tier("solo", 900, 7, 7),
+    "pro": Tier("pro", 1900, 15, 1),
+    "agency": Tier("agency", 4900, 50, 1),
+}
+PAID_TIERS: tuple[str, ...] = ("solo", "pro", "agency")
+RANK: dict[str, int] = {"free": 0, "solo": 1, "pro": 2, "agency": 3}  # best one wins
+
+# Schedule names the forms accept, and the gap each one means. "manual" has no gap.
+SCHEDULE_DAYS: dict[str, int] = {"daily": 1, "weekly": 7, "monthly": 30}
+SCHEDULES: tuple[str, ...] = ("manual", "daily", "weekly", "monthly")
+
+
+# UMBR-66: features beyond saved servers and re-scans, and the cheapest plan that includes each one.
+# The pricing page prints FEATURE_LABELS for every plan that has the feature, so only list what is built.
+FEATURES: dict[str, str] = {
+    "accepted_risk": "solo",
+    "checkin": "solo",
+    "fleet": "pro",
+    "alert_channels": "pro",
+}
+FEATURE_LABELS: dict[str, str] = {
+    "accepted_risk": "Accepted risks: mark a finding as accepted with a reason and an expiry; your score shows both",
+    "checkin": "Scheduled check-ins without SSH access: a cron job on your server uploads a scan; alert if one is missed",
+    "fleet": "Fleet view: every server on one page, worst score first, with trend",
+    "alert_channels": "Score-drop alerts to your own webhook, Slack or Discord, as well as email",
+}
+
+
+def has_feature(tier: Tier, feature: str) -> bool:
+    """True when the tier includes `feature`. An unknown feature is never included (fail closed)."""
+    need = FEATURES.get(feature)
+    return need is not None and RANK.get(tier.name, 0) >= RANK[need]
+
+
+def plan_features(tier: Tier) -> list[str]:
+    """Pricing-card lines for the gated features this tier includes, in FEATURES order."""
+    return [FEATURE_LABELS[f] for f in FEATURES if has_feature(tier, f)]
+
+
+def feature_message(tier: Tier, feature: str) -> str:
+    """Why a gated page is not available on this plan, and which plan has it."""
+    need = TIERS[FEATURES[feature]].label
+    return f"This comes with the {need} plan and up. Your plan is {tier.label}."
+
+
+def tier_of(name: str | None) -> Tier:
+    """The tier for a stored name; anything unknown is treated as free (fail closed)."""
+    return TIERS.get(name or "free", TIERS["free"])
+
+
+def allowed_schedules(tier: Tier) -> list[str]:
+    """Schedule choices the tier may use, fastest first ("manual" is always allowed)."""
+    if tier.min_rescan_days is None:
+        return ["manual"]
+    ok = [s for s, d in SCHEDULE_DAYS.items() if d >= tier.min_rescan_days]
+    return ok + ["manual"]
+
+
+def schedule_allowed(tier: Tier, schedule: str | None) -> bool:
+    return (schedule or "manual") in allowed_schedules(tier)
+
+
+def fastest_schedule(tier: Tier) -> str | None:
+    """The fastest scheduled re-scan the tier may use (None when it may not schedule)."""
+    ok = allowed_schedules(tier)
+    return ok[0] if ok[0] != "manual" else None
+
+
+def server_limit_message(tier: Tier, count: int) -> str:
+    n = tier.max_servers
+    msg = f"Your {tier.label} plan allows {n} saved server{'' if n == 1 else 's'}; you have {count}."
+    if n == 0:
+        return msg + " Saved servers come with a paid plan; see /pricing."
+    return msg + " Delete one, or move to a bigger plan at /pricing."
+
+
+def paused_message(tier: Tier) -> str:
+    """Why a saved server over the plan's limit is paused, and the way back (UMBR-66)."""
+    if tier.max_servers == 0:
+        return (f"Paused: your {tier.label} plan has no saved servers. Nothing is deleted; "
+                "a paid plan resumes it.")
+    return (f"Paused: your {tier.label} plan allows {tier.max_servers} saved servers and this one is over the limit. "
+            "Nothing is deleted; delete another server or move to a bigger plan and it resumes.")
+
+
+def start_offer() -> str:
+    """The cheapest plan that can hold saved servers, as one phrase: '7 servers for $9/month'."""
+    t = TIERS[PAID_TIERS[0]]
+    return f"{t.max_servers} servers for ${t.price_cents // 100}/month"
+
+
+def schedule_message(tier: Tier, schedule: str) -> str:
+    fastest = fastest_schedule(tier)
+    if fastest is None:
+        return f"Scheduled re-scans come with a paid plan. Your {tier.label} plan is manual only; see /pricing."
+    choices = ", ".join(s for s in allowed_schedules(tier) if s != "manual")
+    return (f"Your {tier.label} plan can re-scan {fastest} at most, so {schedule} is not available. "
+            f"Choose {choices} or manual.")