feat(updater): tier 1 — notify admin and pad users of available updates

CHANGELOG.md

@@ -1,3 +1,15 @@
+# Unreleased
+
+### Notable enhancements
+
+- New built-in self-update subsystem (Tier 1: notify).
+  - Periodic check against the GitHub Releases API for the configured repo (default `ether/etherpad`). Configurable via the new `updates.*` settings block, default tier `"notify"`. Set `updates.tier` to `"off"` to disable entirely.
+  - The admin UI shows a banner and a dedicated "Etherpad updates" page with the current version, latest version, install method, and changelog.
+  - Pad users see a discreet footer badge **only** when the running version is severely outdated (one or more major versions behind) or flagged as vulnerable in a recent release manifest. The public endpoint that drives this never leaks the version string itself.
+  - New top-level `adminEmail` setting. When set, the updater emails the admin on first detection of severe / vulnerable status, with escalating cadence (weekly while vulnerable, monthly while severely outdated). PR 1 ships the dedupe + cadence logic; real SMTP wiring lands in a follow-up PR.
+  - Tier 1 ships in this release. Tiers 2 (manual click), 3 (auto with grace window) and 4 (autonomous in maintenance window) are designed and will land in subsequent releases.
+  - See `doc/admin/updates.md` for full configuration.
+
 # 2.7.2
 
 ### Notable enhancements and fixes

admin/src/App.tsx

@@ -6,7 +6,8 @@ import {NavLink, Outlet, useNavigate} from "react-router-dom";
 import {useStore} from "./store/store.ts";
 import {LoadingScreen} from "./utils/LoadingScreen.tsx";
 import {Trans, useTranslation} from "react-i18next";
-import {Cable, Construction, Crown, NotepadText, Wrench, PhoneCall, LucideMenu} from "lucide-react";
+import {Cable, Construction, Crown, NotepadText, Wrench, PhoneCall, LucideMenu, Bell} from "lucide-react";
+import {UpdateBanner} from "./components/UpdateBanner";
 
 const WS_URL = import.meta.env.DEV ? 'http://localhost:9001' : ''
 export const App = () => {
@@ -105,13 +106,15 @@ export const App = () => {
           <li><NavLink to={"/pads"}><NotepadText/><Trans
             i18nKey="ep_admin_pads:ep_adminpads2_manage-pads"/></NavLink></li>
           <li><NavLink to={"/shout"}><PhoneCall/>Communication</NavLink></li>
+          <li><NavLink to={"/update"}><Bell/><Trans i18nKey="update.page.title"/></NavLink></li>
         </ul>
       </div>
     </div>
       <button id="icon-button" onClick={() => {
         setSidebarOpen(!sidebarOpen)
       }}><LucideMenu/></button>
     <div className="innerwrapper">
+      <UpdateBanner/>
       <Outlet/>
     </div>
   </div>

admin/src/components/UpdateBanner.tsx

@@ -0,0 +1,35 @@
+import {useEffect} from 'react';
+import {Link} from 'react-router-dom';
+import {Trans, useTranslation} from 'react-i18next';
+import {useStore} from '../store/store';
+
+export const UpdateBanner = () => {
+  const {t} = useTranslation();
+  const updateStatus = useStore((s) => s.updateStatus);
+  const setUpdateStatus = useStore((s) => s.setUpdateStatus);
+
+  useEffect(() => {
+    let cancelled = false;
+    fetch('/admin/update/status', {credentials: 'same-origin'})
+      .then((r) => r.ok ? r.json() : null)
+      .then((data) => { if (data && !cancelled) setUpdateStatus(data); })
+      .catch(() => {});
+    return () => { cancelled = true; };
+  }, [setUpdateStatus]);
+
+  if (!updateStatus || !updateStatus.latest) return null;
+  if (updateStatus.currentVersion === updateStatus.latest.version) return null;
+
+  return (
+    <div className="update-banner" role="status">
+      <strong><Trans i18nKey="update.banner.title"/></strong>{' '}
+      <span>
+        <Trans
+          i18nKey="update.banner.body"
+          values={{latest: updateStatus.latest.version, current: updateStatus.currentVersion}}
+        />
+      </span>{' '}
+      <Link to="/update">{t('update.banner.cta')}</Link>
+    </div>
+  );
+};

admin/src/index.css

@@ -895,3 +895,30 @@ input, button, select, optgroup, textarea {
 .manage-pads-header {
   display: flex;
 }
+
+/* Update banner — shown on every admin page when a new version is available. */
+.update-banner {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 10px 14px;
+  margin: 0 0 12px 0;
+  background: #fff3cd;
+  color: #664d03;
+  border: 1px solid #ffe69c;
+  border-radius: 4px;
+  font-size: 14px;
+}
+.update-banner a {
+  color: inherit;
+  text-decoration: underline;
+  font-weight: 500;
+}
+
+/* Update page layout. */
+.update-page { padding: 16px 0; }
+.update-page h1 { margin-bottom: 16px; }
+.update-page dl { display: grid; grid-template-columns: max-content 1fr; gap: 6px 16px; margin: 0 0 24px; }
+.update-page dt { font-weight: 600; color: #555; }
+.update-page dd { margin: 0; }
+.update-page pre { background: #f6f8fa; border: 1px solid #d0d7de; border-radius: 4px; padding: 12px; font-size: 13px; max-height: 400px; overflow: auto; }

admin/src/main.tsx

@@ -13,6 +13,7 @@ import i18n from "./localization/i18n.ts";
 import {PadPage} from "./pages/PadPage.tsx";
 import {ToastDialog} from "./utils/Toast.tsx";
 import {ShoutPage} from "./pages/ShoutPage.tsx";
+import {UpdatePage} from "./pages/UpdatePage.tsx";
 
 const router = createBrowserRouter(createRoutesFromElements(
     <><Route element={<App/>}>
@@ -22,6 +23,7 @@ const router = createBrowserRouter(createRoutesFromElements(
         <Route path="/help" element={<HelpPage/>}/>
         <Route path="/pads" element={<PadPage/>}/>
         <Route path="/shout" element={<ShoutPage/>}/>
+        <Route path="/update" element={<UpdatePage/>}/>
     </Route><Route path="/login">
         <Route index element={<LoginScreen/>}/>
     </Route></>

admin/src/pages/UpdatePage.tsx

@@ -0,0 +1,40 @@
+import {Trans, useTranslation} from 'react-i18next';
+import {useStore} from '../store/store';
+
+export const UpdatePage = () => {
+  const {t} = useTranslation();
+  const us = useStore((s) => s.updateStatus);
+
+  if (!us) return <div>{t('admin.loading', {defaultValue: 'Loading...'})}</div>;
+
+  const upToDate = !us.latest || us.currentVersion === us.latest.version;
+
+  return (
+    <div className="update-page">
+      <h1><Trans i18nKey="update.page.title"/></h1>
+      <dl>
+        <dt><Trans i18nKey="update.page.current"/></dt>
+        <dd>{us.currentVersion}</dd>
+        <dt><Trans i18nKey="update.page.latest"/></dt>
+        <dd>{us.latest ? us.latest.version : '—'}</dd>
+        <dt><Trans i18nKey="update.page.last_check"/></dt>
+        <dd>{us.lastCheckAt ?? '—'}</dd>
+        <dt><Trans i18nKey="update.page.install_method"/></dt>
+        <dd>{us.installMethod}</dd>
+        <dt><Trans i18nKey="update.page.tier"/></dt>
+        <dd>{us.tier}</dd>
+      </dl>
+      {upToDate ? (
+        <p><Trans i18nKey="update.page.up_to_date"/></p>
+      ) : us.latest ? (
+        <>
+          <h2><Trans i18nKey="update.page.changelog"/></h2>
+          <pre style={{whiteSpace: 'pre-wrap'}}>{us.latest.body}</pre>
+          <p><a href={us.latest.htmlUrl} rel="noreferrer noopener" target="_blank">{us.latest.htmlUrl}</a></p>
+        </>
+      ) : null}
+    </div>
+  );
+};
+
+export default UpdatePage;

admin/src/store/store.ts

@@ -3,6 +3,23 @@ import {Socket} from "socket.io-client";
 import {PadSearchResult} from "../utils/PadSearch.ts";
 import {InstalledPlugin} from "../pages/Plugin.ts";
 
+export interface UpdateStatusPayload {
+  currentVersion: string;
+  latest: null | {
+    version: string;
+    tag: string;
+    body: string;
+    publishedAt: string;
+    prerelease: boolean;
+    htmlUrl: string;
+  };
+  lastCheckAt: string | null;
+  installMethod: string;
+  tier: string;
+  policy: null | {canNotify: boolean; canManual: boolean; canAuto: boolean; canAutonomous: boolean; reason: string};
+  vulnerableBelow: Array<{announcedBy: string; threshold: string}>;
+}
+
 type ToastState = {
   description?:string,
   title: string,
@@ -25,7 +42,9 @@ type StoreState = {
   pads: PadSearchResult|undefined,
   setPads: (pads: PadSearchResult)=>void,
   installedPlugins: InstalledPlugin[],
-  setInstalledPlugins: (plugins: InstalledPlugin[])=>void
+  setInstalledPlugins: (plugins: InstalledPlugin[])=>void,
+  updateStatus: UpdateStatusPayload | null,
+  setUpdateStatus: (s: UpdateStatusPayload) => void,
 }
 
 
@@ -48,5 +67,7 @@ export const useStore = create<StoreState>()((set) => ({
   pads: undefined,
   setPads: (pads)=>set({pads}),
   installedPlugins: [],
-  setInstalledPlugins: (plugins)=>set({installedPlugins: plugins})
+  setInstalledPlugins: (plugins)=>set({installedPlugins: plugins}),
+  updateStatus: null,
+  setUpdateStatus: (s) => set({updateStatus: s}),
 }));

doc/admin/updates.md

@@ -0,0 +1,83 @@
+# Etherpad updates
+
+Etherpad ships with a built-in update subsystem. **Tier 1 (notify)** is enabled by default: a banner appears in the admin UI when a new release is available, and pad users see a discreet badge if the running version is severely outdated or flagged as vulnerable. No automatic execution happens at this tier — admins are simply informed.
+
+Tiers 2 (manual click), 3 (auto with grace window), and 4 (autonomous in maintenance window) are designed but not yet implemented. They will land in subsequent releases.
+
+## Settings
+
+In `settings.json`:
+
+```jsonc
+{
+  "updates": {
+    "tier": "notify",
+    "source": "github",
+    "channel": "stable",
+    "installMethod": "auto",
+    "checkIntervalHours": 6,
+    "githubRepo": "ether/etherpad",
+    "requireAdminForStatus": false
+  },
+  "adminEmail": null
+}
+```
+
+| Setting | Default | Notes |
+| --- | --- | --- |
+| `updates.tier` | `"notify"` | One of `"off"`, `"notify"`, `"manual"`, `"auto"`, `"autonomous"`. Higher tiers are silently downgraded if the install method does not allow them. PR 1 only honors `"notify"` and `"off"`. |
+| `updates.source` | `"github"` | Reserved for future alternative sources. Only `"github"` is implemented. |
+| `updates.channel` | `"stable"` | Reserved. Stable releases only. |
+| `updates.installMethod` | `"auto"` | One of `"auto"`, `"git"`, `"docker"`, `"npm"`, `"managed"`. Auto-detects via filesystem heuristics. Set explicitly to override. |
+| `updates.checkIntervalHours` | `6` | How often to poll GitHub Releases. |
+| `updates.githubRepo` | `"ether/etherpad"` | Override for forks. |
+| `updates.requireAdminForStatus` | `false` | Lock the `/admin/update/status` endpoint to authenticated admin sessions. Default `false` matches existing Etherpad behavior — `/health` already exposes `releaseId` publicly, and changelog data comes from a public GitHub release. Set `true` to hide the full update payload from non-admins without disabling the updater (`tier: "off"` is the heavier opt-out that removes the endpoints entirely). |
+| `adminEmail` | `null` | Top-level. Contact for admin notifications. Setting it enables the email nudges below. |
+
+## What "outdated" means
+
+- **`severe`** — running at least one major version behind the latest release.
+- **`vulnerable`** — the running version is below a `vulnerable-below` threshold announced in a recent release. Releases declare these via a `<!-- updater: vulnerable-below X.Y.Z -->` HTML comment in their body. The newest such directive wins.
+
+## Email cadence (when `adminEmail` is set)
+
+| Trigger | First send | Repeat |
+| --- | --- | --- |
+| Vulnerable status detected | Immediate | Weekly while still vulnerable |
+| New release announced while still vulnerable | Immediate | n/a (one event per tag change) |
+| Severely outdated detected | Immediate | Monthly while still severely outdated |
+| Up to date | No email | — |
+
+If `adminEmail` is unset, the updater never sends mail. The admin UI banner and the pad-side badge still work without it.
+
+PR 1 ships the cadence machinery but does not yet wire a real SMTP transport — emails are logged with `(would send email)` until a future PR adds the transport. The dedupe state still advances correctly so admins are not bombarded once SMTP is wired.
+
+## Pad-side badge
+
+Pad users see no version information by default. A small badge appears in the bottom-right corner only when:
+
+- The instance is `severe` (one or more major versions behind), or
+- The instance is `vulnerable` (running below an announced threshold).
+
+The public endpoint `/api/version-status` returns only `{outdated: null|"severe"|"vulnerable"}` — it never leaks the running version, so attackers do not gain a fingerprint vector.
+
+## Disabling everything
+
+Set `updates.tier` to `"off"`. No HTTP request will leave the instance and no banner or badge will render.
+
+## Privacy
+
+The version check sends no telemetry. Etherpad fetches the public GitHub Releases API (`api.github.com/repos/<repo>/releases/latest`) with `If-None-Match` to be cache-friendly. The only metadata GitHub sees is the same as any other GitHub API client — your IP and a `User-Agent: etherpad-self-update` header. No instance ID, no version, no identifiers travel upstream.
+
+## How install method is detected
+
+`updates.installMethod` defaults to `"auto"`, which uses these heuristics in order:
+
+1. `/.dockerenv` exists → `"docker"`.
+2. `.git/` directory present and the install root is writable → `"git"`.
+3. `package-lock.json` present and writable → `"npm"`.
+4. Otherwise → `"managed"`.
+
+Set the value explicitly if the heuristics get it wrong (e.g., a docker container that bind-mounts a writable git checkout).
+
+In PR 1 (notify only) the install method does not change behavior — every install method gets the banner. From PR 2 onward the install method gates whether the manual-click and automatic tiers can run; only `"git"` is initially supported for write tiers.