@bevel-software/platform-core-backend 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bevel-software/platform-core-backend",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Open-source core backend of the Bevel platform: git-backed knowledge workspace, workflow (branches/change requests/locks/SSE), skills, tools, secrets vault, access control and the remote MCP surface.",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,7 +34,7 @@
     "@utcp/code-mode": "^1.2.12",
     "@utcp/direct-call": "^1.1.1",
     "@utcp/http": "^1.1.7",
-    "@utcp/mcp": "^1.1.3",
+    "@utcp/mcp": "^1.1.4",
     "@utcp/sdk": "^1.1.1",
     "adm-zip": "^0.6.0",
     "cors": "^2.8.5",
@@ -46,8 +46,8 @@
     "pg": "^8.20.0",
     "yaml": "^2.9.0",
     "zod": "^3.24.0",
-    "@bevel-software/platform-mcp-core": "0.9.0",
-    "@bevel-software/platform-shared": "0.9.0"
+    "@bevel-software/platform-mcp-core": "0.10.0",
+    "@bevel-software/platform-shared": "0.10.0"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.8",

package/src/__tests__/core-config.domain.test.ts

@@ -0,0 +1,92 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { CoreConfig } from '../core-config.js';
+
+/**
+ * The public-shape derivation from `DOMAIN`.
+ *
+ * Setting `DOMAIN` declares "the bundled Caddy `https` profile fronts this
+ * deployment": one proxy hop, origins = the domain. The config derives
+ * `PUBLIC_BACKEND_URL` / `PUBLIC_FRONTEND_URL` (`https://<DOMAIN>`) and
+ * `TRUST_PROXY` (`1`) from it — but only as DEFAULTS: an explicit value for
+ * any of the three always wins, so a CDN in front of Caddy or a frontend
+ * served elsewhere stays expressible.
+ */
+const REQUIRED = {
+  KB_REPO_URL: 'https://example.com/org/kb.git',
+  ADMIN_EMAIL: 'root@example.com',
+  ADMIN_PASSWORD: 'sup3r-secret',
+  JWT_SECRET: 'test-jwt-secret',
+  SECRETS_ENC_KEY: 'kToAi8FXWDpDn3A6yQ/60O39bv05N7XzVOIu/0CJrFc=',
+};
+
+let saved: NodeJS.ProcessEnv;
+
+beforeEach(() => {
+  saved = { ...process.env };
+  // A clean slate for the keys under test (a developer .env loaded by
+  // dotenv at import time may carry any of them).
+  for (const key of [
+    'DOMAIN',
+    'PUBLIC_BACKEND_URL',
+    'PUBLIC_FRONTEND_URL',
+    'TRUST_PROXY',
+    'NODE_ENV',
+    'PORT',
+  ]) {
+    delete process.env[key];
+  }
+  Object.assign(process.env, REQUIRED);
+});
+
+afterEach(() => {
+  process.env = saved;
+});
+
+describe('CoreConfig — DOMAIN derives the public shape', () => {
+  it('DOMAIN alone yields https origins and one proxy hop', () => {
+    process.env.DOMAIN = 'bevel.example.com';
+    const config = new CoreConfig();
+    expect(config.publicBackendUrl).toBe('https://bevel.example.com');
+    expect(config.publicFrontendUrl).toBe('https://bevel.example.com');
+    expect(config.trustProxy).toBe('1');
+  });
+
+  it('explicit PUBLIC_* and TRUST_PROXY always win over DOMAIN', () => {
+    // The CDN-in-front-of-Caddy shape: two hops, and a frontend served from
+    // somewhere the bundled proxy is not.
+    process.env.DOMAIN = 'bevel.example.com';
+    process.env.PUBLIC_BACKEND_URL = 'https://api.example.com';
+    process.env.PUBLIC_FRONTEND_URL = 'https://app.example.com';
+    process.env.TRUST_PROXY = '2';
+    const config = new CoreConfig();
+    expect(config.publicBackendUrl).toBe('https://api.example.com');
+    expect(config.publicFrontendUrl).toBe('https://app.example.com');
+    expect(config.trustProxy).toBe('2');
+  });
+
+  it('without DOMAIN the defaults are unchanged (dev shape)', () => {
+    const config = new CoreConfig();
+    expect(config.publicBackendUrl).toBe('http://localhost:3001');
+    expect(config.publicFrontendUrl).toBe('http://localhost:5173');
+    // Unset means "directly exposed": forwarded headers stay ignored.
+    expect(config.trustProxy).toBe('');
+  });
+
+  it('without DOMAIN in production, the frontend origin is the backend origin', () => {
+    // The backend serves the built SPA — under docker compose (which sets
+    // NODE_ENV=production and no PUBLIC_* by default) this is what keeps a
+    // bare `up -d` bouncing logins back to the container's own origin.
+    process.env.NODE_ENV = 'production';
+    const config = new CoreConfig();
+    expect(config.publicBackendUrl).toBe('http://localhost:3001');
+    expect(config.publicFrontendUrl).toBe('http://localhost:3001');
+    expect(config.trustProxy).toBe('');
+  });
+
+  it('an explicit production backend origin carries over to the frontend default', () => {
+    process.env.NODE_ENV = 'production';
+    process.env.PUBLIC_BACKEND_URL = 'https://bevel.example.com';
+    const config = new CoreConfig();
+    expect(config.publicFrontendUrl).toBe('https://bevel.example.com');
+  });
+});

package/src/core/create-core-server.ts

@@ -28,6 +28,7 @@ import {
   createSecretsVaultPublicRoutes,
 } from '../modules/secrets-vault/index.js';
 import { createAdminAccessRoutes } from '../modules/admin/admin-access.routes.js';
+import { createUpdateCheckRoutes } from '../modules/update-check/update-check.routes.js';
 import { createAccountRoutes } from '../modules/auth/account.routes.js';
 import { createSetupRoutes } from '../modules/settings/setup.routes.js';
 import { DEFAULT_BRANCH, PROTECTED_BRANCHES, type AuthUser } from '@bevel-software/platform-shared';
@@ -426,6 +427,13 @@ export async function createCoreServer(
   // Admin-status resolver (CORE — see the note in admin-access.routes.ts;
   // the full admin router is an enterprise `ext.authed` extension).
   app.use('/api', core.authMiddleware, createAdminAccessRoutes(core.adminAccess));
+  // Update check (admin-only inside): the newest published release vs the
+  // running version, cached server-side — see update-check.service.ts.
+  app.use(
+    '/api',
+    core.authMiddleware,
+    createUpdateCheckRoutes(core.updateCheckService, core.adminAccess),
+  );
   // Account management (list/create password accounts, GDPR erasure) —
   // admin-gated inside.
   app.use('/api', core.authMiddleware, createAccountRoutes(

package/src/core/create-core-services.ts

@@ -82,6 +82,8 @@ import { ToolRegistry } from '../modules/tool-registry/tool-registry.js';
 import { createToolContextResolver } from '../modules/tool-helpers/tool-context.js';
 import { createToolHandlerFactory } from '../modules/tool-helpers/tool-handler.js';
 import { TokenCrypto } from '../shared/token-crypto.js';
+import { UpdateCheckService } from '../modules/update-check/update-check.service.js';
+import { resolveAppVersion } from '../version.js';
 import { noopRecoveryAgent, type CorePorts } from './core-ports.js';
 
 /**
@@ -131,6 +133,8 @@ export interface CoreServices {
   pendingCommitsWorker: PendingCommitsWorker;
   recoveryBot: AuthUser;
   adminAccess: AdminAccessService;
+  /** Newest-release lookup behind `GET /api/update-check` (admin-only). */
+  updateCheckService: UpdateCheckService;
   /** Deployment settings, env-first — the KB remote resolves through these. */
   settings: DeploymentSettingsService;
   /**
@@ -499,6 +503,15 @@ export async function createCoreServices(
     [config.adminEmail],
   );
 
+  // In-app update check: lazily compares the running release version against
+  // the newest published GitHub release, only when an admin's browser asks —
+  // no timers, so a deployment nobody looks at makes zero calls. The flag
+  // removes even that (air-gapped deployments; see CoreConfig).
+  const updateCheckService = new UpdateCheckService({
+    enabled: config.updateCheckEnabled,
+    currentVersion: resolveAppVersion(),
+  });
+
   // Secrets Vault: the per-user store of credentials (static API keys + OAuth
   // tokens) that back UTCP tool variables (`${FOO_API_KEY}`). Encrypted at rest
   // with the connector-config key; read only by the `bevel-secrets` variable
@@ -746,6 +759,7 @@ export async function createCoreServices(
     pendingCommitsWorker,
     recoveryBot,
     adminAccess,
+    updateCheckService,
     secretsVaultService,
     externalApiKeyService,
     internalTokenService,

package/src/core-config.ts

@@ -144,6 +144,16 @@ export class CoreConfig {
    * `session-ontology.gate.ts`), so it must exist wherever the tracking runs.
    */
   readonly ontologySessionBlock: boolean;
+  /**
+   * In-app update check. When true (default), `GET /api/update-check` lazily
+   * asks api.github.com for the newest Hexis release — only when an admin's
+   * browser asks, cached for hours, never on a timer — so admins see a quiet
+   * banner when this deployment is behind. The request carries nothing but
+   * the request itself: no token, no identifier, no telemetry. Set
+   * `UPDATE_CHECK=false` for air-gapped deployments or anyone who objects to
+   * the phone-home; disabled, the server never makes the call.
+   */
+  readonly updateCheckEnabled: boolean;
   /**
    * Password-login toggle for the login screen. Default enabled; set
    * `LOGIN_PASSWORD=false` to hide the method AND reject `/auth/login`
@@ -203,14 +213,22 @@ export class CoreConfig {
    * but behind a proxy it makes every client share the proxy's IP (so the
    * per-IP login rate limit would pool all users). Set it to the actual hop
    * count — never a blanket trust — so clients can't spoof X-Forwarded-For.
+   * With `DOMAIN` set (the bundled Caddy fronts the deployment) it defaults
+   * to `1` instead — see the derivation in the constructor.
    */
   readonly trustProxy: string;
   /**
    * Public base URL of THIS backend, used to build OAuth redirect URIs.
    * Must match a redirect URI registered with the OAuth provider(s).
+   * Defaults to `https://<DOMAIN>` when `DOMAIN` is set.
    */
   readonly publicBackendUrl: string;
-  /** Public base URL of the frontend, where callbacks redirect post-login. */
+  /**
+   * Public base URL of the frontend, where callbacks redirect post-login.
+   * Defaults to `https://<DOMAIN>` when `DOMAIN` is set, else to the backend
+   * origin in production (the backend serves the SPA) and Vite's `:5173` in
+   * development.
+   */
   readonly publicFrontendUrl: string;
 
   constructor() {
@@ -304,6 +322,8 @@ export class CoreConfig {
     this.kbTemplateDir = process.env.KB_TEMPLATE_DIR || defaultKbTemplateDir();
     this.ontologySessionBlock =
       (process.env.ONTOLOGY_SESSION_BLOCK ?? 'true').trim().toLowerCase() !== 'false';
+    this.updateCheckEnabled =
+      (process.env.UPDATE_CHECK ?? 'true').trim().toLowerCase() !== 'false';
     this.allowedEmailDomains = (process.env.ALLOWED_EMAIL_DOMAINS || '')
       .split(/[\s,]+/)
       .map((d) => d.trim().toLowerCase().replace(/^[@.]+/, ''))
@@ -322,11 +342,35 @@ export class CoreConfig {
       );
     }
     this.internalTokenSecret = (process.env.INTERNAL_TOKEN_SECRET || '').trim();
-    this.trustProxy = (process.env.TRUST_PROXY || '').trim();
-    this.publicBackendUrl = (process.env.PUBLIC_BACKEND_URL || `http://localhost:${this.port}`)
+    // Setting DOMAIN declares "the bundled Caddy `https` profile fronts this
+    // deployment" — one proxy hop, and the public origin IS that domain. The
+    // three values below therefore default from it, so `DOMAIN=x.example.com`
+    // in `.env` is the whole configuration for that shape: TRUST_PROXY falls
+    // to 1 (Caddy is the hop) and both public URLs to `https://<DOMAIN>` (the
+    // backend serves the SPA, so they share an origin). Explicit
+    // PUBLIC_BACKEND_URL / PUBLIC_FRONTEND_URL / TRUST_PROXY always win — a
+    // CDN in front of Caddy (TRUST_PROXY=2) or a frontend served elsewhere
+    // stays expressible.
+    const domain = (process.env.DOMAIN || '').trim();
+    this.trustProxy = (process.env.TRUST_PROXY || (domain ? '1' : '')).trim();
+    this.publicBackendUrl = (
+      process.env.PUBLIC_BACKEND_URL ||
+      (domain ? `https://${domain}` : `http://localhost:${this.port}`)
+    )
       .trim()
       .replace(/\/+$/, '');
-    this.publicFrontendUrl = (process.env.PUBLIC_FRONTEND_URL || 'http://localhost:5173')
+    // Unset, the frontend origin is the backend's own in production (the
+    // backend serves the built SPA — under docker compose this is what makes
+    // a bare `up -d` bounce logins back to the right place), and Vite's dev
+    // server in development.
+    this.publicFrontendUrl = (
+      process.env.PUBLIC_FRONTEND_URL ||
+      (domain
+        ? `https://${domain}`
+        : this.nodeEnv === 'production'
+          ? this.publicBackendUrl
+          : 'http://localhost:5173')
+    )
       .trim()
       .replace(/\/+$/, '');
     // Parse-validate so a malformed URL fails at boot rather than producing a

package/src/modules/update-check/__tests__/update-check.routes.test.ts

@@ -0,0 +1,69 @@
+import type { Server as HttpServer } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import express from 'express';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createUpdateCheckRoutes } from '../update-check.routes.js';
+import type { UpdateCheckService } from '../update-check.service.js';
+
+/**
+ * GET /api/update-check — admin-only. Non-admins get the same 403 the setup
+ * routes give (the frontend only asks on behalf of admins anyway), and the
+ * service is never consulted for them.
+ */
+
+let server: HttpServer | null = null;
+
+afterEach(() => {
+  server?.close();
+  server = null;
+  vi.restoreAllMocks();
+});
+
+function listen(
+  service: Pick<UpdateCheckService, 'check'>,
+  opts: { email?: string; admins?: string[] } = {},
+): string {
+  const app = express();
+  const middleware: express.RequestHandler = (req, _res, next) => {
+    req.userEmail = opts.email ?? 'user@example.com';
+    next();
+  };
+  const adminAccess = {
+    isAdmin: async (email: string | undefined) =>
+      (opts.admins ?? ['admin@example.com']).includes(email ?? ''),
+  };
+  app.use('/api', middleware, createUpdateCheckRoutes(service, adminAccess));
+  server = app.listen(0);
+  const { port } = server.address() as AddressInfo;
+  return `http://127.0.0.1:${port}`;
+}
+
+describe('GET /update-check', () => {
+  it('answers the full shape for an admin', async () => {
+    const check = vi.fn().mockResolvedValue({
+      updateAvailable: true,
+      current: '0.9.1',
+      latest: '0.10.0',
+      notesUrl: 'https://github.com/Bevel-Software/Hexis/releases/tag/v0.10.0',
+    });
+    const base = listen({ check }, { email: 'admin@example.com' });
+    const res = await fetch(`${base}/api/update-check`);
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({
+      updateAvailable: true,
+      current: '0.9.1',
+      latest: '0.10.0',
+      notesUrl: 'https://github.com/Bevel-Software/Hexis/releases/tag/v0.10.0',
+    });
+    expect(check).toHaveBeenCalledTimes(1);
+  });
+
+  it('403s a non-admin without consulting the service', async () => {
+    const check = vi.fn();
+    const base = listen({ check }, { email: 'user@example.com' });
+    const res = await fetch(`${base}/api/update-check`);
+    expect(res.status).toBe(403);
+    expect(await res.json()).toEqual({ error: 'Admins only' });
+    expect(check).not.toHaveBeenCalled();
+  });
+});

package/src/modules/update-check/__tests__/update-check.service.test.ts

@@ -0,0 +1,170 @@
+import { describe, expect, it, vi } from 'vitest';
+import {
+  UpdateCheckService,
+  isNewerVersion,
+  parseReleaseVersion,
+} from '../update-check.service.js';
+
+/**
+ * The update check's contract: lazy, cached, and SILENT on failure. The one
+ * thing it must never do is turn an offline deployment (or a GitHub hiccup,
+ * or a weird tag) into an error a user sees — every degraded path resolves to
+ * `updateAvailable: false`.
+ */
+
+/** A fetch stub answering like the GitHub releases endpoint. */
+function githubFetch(tag: string, notesUrl = 'https://github.com/Bevel-Software/Hexis/releases/tag/' + tag) {
+  return vi.fn().mockResolvedValue({
+    ok: true,
+    json: async () => ({ tag_name: tag, html_url: notesUrl }),
+  }) as unknown as typeof fetch & ReturnType<typeof vi.fn>;
+}
+
+function service(opts: {
+  enabled?: boolean;
+  current?: string;
+  fetchFn?: typeof fetch;
+  now?: () => number;
+}) {
+  return new UpdateCheckService({
+    enabled: opts.enabled ?? true,
+    currentVersion: opts.current ?? '0.9.1',
+    fetchFn: opts.fetchFn,
+    now: opts.now,
+  });
+}
+
+describe('version comparison', () => {
+  it('compares numerically per part, not as strings', () => {
+    expect(isNewerVersion('0.10.0', '0.9.1')).toBe(true);
+    expect(isNewerVersion('1.0.0', '0.99.99')).toBe(true);
+    expect(isNewerVersion('0.9.2', '0.9.1')).toBe(true);
+  });
+
+  it('equal or older is not newer', () => {
+    expect(isNewerVersion('0.9.1', '0.9.1')).toBe(false);
+    expect(isNewerVersion('0.9.0', '0.9.1')).toBe(false);
+    expect(isNewerVersion('0.8.9', '0.9.1')).toBe(false);
+  });
+
+  it('tolerates a leading v and refuses prerelease/malformed tags', () => {
+    expect(parseReleaseVersion('v0.10.0')).toEqual([0, 10, 0]);
+    expect(parseReleaseVersion('0.10.0-rc.1')).toBeNull();
+    expect(parseReleaseVersion('nightly')).toBeNull();
+    expect(parseReleaseVersion('')).toBeNull();
+    expect(isNewerVersion('0.10.0-rc.1', '0.9.1')).toBe(false);
+  });
+
+  it('an unparseable RUNNING version never announces an update', () => {
+    // `resolveAppVersion` answers 'unknown' when the manifest is unreadable —
+    // that must fail toward silence, not toward "everything is newer".
+    expect(isNewerVersion('0.10.0', 'unknown')).toBe(false);
+  });
+});
+
+describe('UpdateCheckService.check', () => {
+  it('reports an update when the published release is newer', async () => {
+    const fetchFn = githubFetch('v0.10.0');
+    const result = await service({ fetchFn }).check();
+    expect(result).toEqual({
+      updateAvailable: true,
+      current: '0.9.1',
+      latest: '0.10.0',
+      notesUrl: 'https://github.com/Bevel-Software/Hexis/releases/tag/v0.10.0',
+    });
+    // No credentials, ever — the request is the whole payload.
+    const [, init] = fetchFn.mock.calls[0] as [string, RequestInit];
+    expect(new Headers(init.headers).has('authorization')).toBe(false);
+    expect(new Headers(init.headers).get('accept')).toBe('application/vnd.github+json');
+  });
+
+  it('reports no update when equal or when the deployment is ahead', async () => {
+    expect(await service({ fetchFn: githubFetch('v0.9.1') }).check()).toMatchObject({
+      updateAvailable: false,
+      current: '0.9.1',
+      latest: '0.9.1',
+    });
+    expect(
+      await service({ fetchFn: githubFetch('v0.9.0'), current: '0.9.1' }).check(),
+    ).toMatchObject({ updateAvailable: false });
+  });
+
+  it('resolves a prerelease or malformed tag to "no update" without throwing', async () => {
+    const result = await service({ fetchFn: githubFetch('v0.10.0-rc.1') }).check();
+    expect(result.updateAvailable).toBe(false);
+    // A tag that didn't parse is not offered as "latest".
+    expect(result.latest).toBeUndefined();
+  });
+
+  it('refuses a double-prefixed tag — vv99.0.0 must not shed one v and pass', async () => {
+    // The RAW tag is what gets validated: stripping first would leave v99.0.0,
+    // which the parser's lenient `v?` accepts.
+    const result = await service({ fetchFn: githubFetch('vv99.0.0') }).check();
+    expect(result.updateAvailable).toBe(false);
+    expect(result.latest).toBeUndefined();
+  });
+
+  it('disabled: answers immediately and never touches the network', async () => {
+    const fetchFn = githubFetch('v99.0.0');
+    const result = await service({ enabled: false, fetchFn }).check();
+    expect(result).toEqual({ updateAvailable: false, current: '0.9.1' });
+    expect(fetchFn).not.toHaveBeenCalled();
+  });
+
+  it('a failed fetch is silent, and cached so a dead network is not re-probed', async () => {
+    let now = 0;
+    const fetchFn = vi.fn().mockRejectedValue(new Error('ENOTFOUND api.github.com'));
+    const svc = service({ fetchFn: fetchFn as unknown as typeof fetch, now: () => now });
+
+    expect(await svc.check()).toEqual({ updateAvailable: false, current: '0.9.1' });
+    // Within the failure TTL (~15min): served from cache.
+    now = 14 * 60 * 1000;
+    await svc.check();
+    expect(fetchFn).toHaveBeenCalledTimes(1);
+    // Past it: retried.
+    now = 16 * 60 * 1000;
+    await svc.check();
+    expect(fetchFn).toHaveBeenCalledTimes(2);
+  });
+
+  it('a success is cached for hours across requests', async () => {
+    let now = 0;
+    const fetchFn = githubFetch('v0.10.0');
+    const svc = service({ fetchFn, now: () => now });
+
+    const first = await svc.check();
+    now = 5 * 60 * 60 * 1000; // 5h — inside the 6h TTL
+    const second = await svc.check();
+    expect(second).toEqual(first);
+    expect(fetchFn).toHaveBeenCalledTimes(1);
+
+    now = 7 * 60 * 60 * 1000; // past the TTL — refreshed
+    await svc.check();
+    expect(fetchFn).toHaveBeenCalledTimes(2);
+  });
+
+  it('concurrent requests share one in-flight fetch', async () => {
+    let release!: (value: unknown) => void;
+    const gate = new Promise((resolve) => {
+      release = resolve;
+    });
+    const fetchFn = vi.fn().mockImplementation(async () => {
+      await gate;
+      return { ok: true, json: async () => ({ tag_name: 'v0.10.0', html_url: 'u' }) };
+    });
+    const svc = service({ fetchFn: fetchFn as unknown as typeof fetch });
+
+    const [a, b] = [svc.check(), svc.check()];
+    release(undefined);
+    expect(await a).toEqual(await b);
+    expect(fetchFn).toHaveBeenCalledTimes(1);
+  });
+
+  it('treats a non-2xx answer like any other failure: silent false', async () => {
+    const fetchFn = vi
+      .fn()
+      .mockResolvedValue({ ok: false, status: 403, json: async () => ({}) });
+    const result = await service({ fetchFn: fetchFn as unknown as typeof fetch }).check();
+    expect(result).toEqual({ updateAvailable: false, current: '0.9.1' });
+  });
+});

package/src/modules/update-check/update-check.routes.ts

@@ -0,0 +1,28 @@
+import express from 'express';
+import type { IAdminAccessService } from '../admin/admin.interface.js';
+import type { UpdateCheckService } from './update-check.service.js';
+import '../auth/auth.middleware.js'; // Express Request augmentation
+
+/**
+ * `GET /api/update-check` — ADMIN-ONLY (same `requireAdmin` shape as the setup
+ * routes): admins are the audience of the banner and the only ones who can act
+ * on it, and there is no reason to narrate the deployment's patch level to
+ * everyone else. The service behind it does the caching, so this is safe to
+ * call as often as the frontend likes.
+ */
+export function createUpdateCheckRoutes(
+  service: Pick<UpdateCheckService, 'check'>,
+  adminAccess: IAdminAccessService,
+): express.Router {
+  const router = express.Router();
+
+  router.get('/update-check', async (req, res) => {
+    if (!(await adminAccess.isAdmin(req.userEmail))) {
+      res.status(403).json({ error: 'Admins only' });
+      return;
+    }
+    res.json(await service.check());
+  });
+
+  return router;
+}

package/src/modules/update-check/update-check.service.ts

@@ -0,0 +1,130 @@
+/**
+ * In-app update check — the server learns the newest published Hexis release
+ * and tells admins when the running deployment is behind (the pattern Immich
+ * and Gitea use: a quiet banner, no auto-anything).
+ *
+ * Deliberate shape:
+ *
+ *  - LAZY, never on a timer. The first `check()` triggers the fetch; a
+ *    deployment nobody looks at makes zero calls. Results are cached (~6h),
+ *    concurrent callers share one in-flight request.
+ *  - The request goes to api.github.com and carries NOTHING but itself — no
+ *    auth token (public repo; this must never hold credentials), no
+ *    identifier, no telemetry. `UPDATE_CHECK=false` removes even that.
+ *  - FAILURE IS SILENT. Offline and air-gapped deployments must stay quiet,
+ *    not broken: a failed fetch is cached briefly (~15min, so a dead network
+ *    isn't re-probed per request) and reported as "no update available".
+ *  - Only a clean `x.y.z` newer than the running version counts. Prerelease
+ *    or malformed tags — and a running version we can't parse — resolve to
+ *    "no update" rather than a guess or a throw.
+ */
+
+export interface UpdateCheckResult {
+  updateAvailable: boolean;
+  /** The running version (this build's release version). */
+  current: string;
+  /** Newest published release, when the check reached GitHub and parsed one. */
+  latest?: string;
+  /** The release-notes page of that release. */
+  notesUrl?: string;
+}
+
+const RELEASES_LATEST_URL =
+  'https://api.github.com/repos/Bevel-Software/Hexis/releases/latest';
+const SUCCESS_TTL_MS = 6 * 60 * 60 * 1000;
+const FAILURE_TTL_MS = 15 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 5_000;
+
+/** `v1.2.3` / `1.2.3` → `[1,2,3]`; anything else (prerelease included) → null. */
+export function parseReleaseVersion(raw: string): [number, number, number] | null {
+  const m = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(raw.trim());
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+/**
+ * Whether `latest` is STRICTLY newer than `current`. Numeric per-part compare
+ * (no string compare — `0.10.0` > `0.9.1`). Either side failing to parse is
+ * `false`: an answer we can't trust is not an update announcement.
+ */
+export function isNewerVersion(latest: string, current: string): boolean {
+  const a = parseReleaseVersion(latest);
+  const b = parseReleaseVersion(current);
+  if (!a || !b) return false;
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) return a[i] > b[i];
+  }
+  return false;
+}
+
+export class UpdateCheckService {
+  private cached: { result: UpdateCheckResult; expiresAt: number } | null = null;
+  private inFlight: Promise<UpdateCheckResult> | null = null;
+
+  constructor(
+    private readonly opts: {
+      /** `UPDATE_CHECK` — false means no network, ever. */
+      enabled: boolean;
+      /** The running release version (see `resolveAppVersion`). */
+      currentVersion: string;
+      /** Injectable for tests; defaults to global fetch. */
+      fetchFn?: typeof fetch;
+      /** Injectable for tests; defaults to the GitHub releases endpoint. */
+      releasesUrl?: string;
+      /** Injectable clock for TTL tests; defaults to Date.now. */
+      now?: () => number;
+    },
+  ) {}
+
+  async check(): Promise<UpdateCheckResult> {
+    if (!this.opts.enabled) {
+      return { updateAvailable: false, current: this.opts.currentVersion };
+    }
+    const now = (this.opts.now ?? Date.now)();
+    if (this.cached && now < this.cached.expiresAt) return this.cached.result;
+    // One request serves every concurrent caller; `finally` clears the slot so
+    // the NEXT check after settlement reads the cache (or starts a fresh
+    // fetch once the TTL lapses).
+    this.inFlight ??= this.fetchAndCache().finally(() => {
+      this.inFlight = null;
+    });
+    return this.inFlight;
+  }
+
+  private async fetchAndCache(): Promise<UpdateCheckResult> {
+    const current = this.opts.currentVersion;
+    const nowFn = this.opts.now ?? Date.now;
+    try {
+      const fetchFn = this.opts.fetchFn ?? fetch;
+      const res = await fetchFn(this.opts.releasesUrl ?? RELEASES_LATEST_URL, {
+        headers: { Accept: 'application/vnd.github+json' },
+        signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+      });
+      if (!res.ok) throw new Error(`GitHub answered ${res.status}`);
+      const body = (await res.json()) as { tag_name?: unknown; html_url?: unknown };
+      const tag = typeof body.tag_name === 'string' ? body.tag_name.trim() : '';
+      // Validate the RAW tag before normalizing: a malformed `vv1.2.3` would
+      // otherwise shed one prefix and land on `v1.2.3`, which the parser's
+      // lenient `v?` then accepts — announcing a tag we should distrust.
+      const latest = parseReleaseVersion(tag) ? tag.replace(/^v/, '') : '';
+      const notesUrl = typeof body.html_url === 'string' ? body.html_url : undefined;
+      const result: UpdateCheckResult = isNewerVersion(latest, current)
+        ? { updateAvailable: true, current, latest, notesUrl }
+        : // Equal, older, prerelease or malformed: all "no update". `latest`
+          // rides along only when it parsed — a garbage tag is not an answer.
+          {
+            updateAvailable: false,
+            current,
+            ...(parseReleaseVersion(latest) ? { latest } : {}),
+          };
+      this.cached = { result, expiresAt: nowFn() + SUCCESS_TTL_MS };
+      return result;
+    } catch {
+      // Silent by design — no log spam, no error to the UI. The short TTL is
+      // what keeps a dead network from being probed on every request.
+      const result: UpdateCheckResult = { updateAvailable: false, current };
+      this.cached = { result, expiresAt: nowFn() + FAILURE_TTL_MS };
+      return result;
+    }
+  }
+}