@arcforgelabs/flow 0.0.0-stage → 2026.10.18

package/server/db/migrations/meta/_journal.json

@@ -0,0 +1,27 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1792133499599,
+      "tag": "0000_core",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "7",
+      "when": 1792133500543,
+      "tag": "0001_records_are_append_only",
+      "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "7",
+      "when": 1792322911044,
+      "tag": "0002_people",
+      "breakpoints": true
+    }
+  ]
+}

package/server/db/schema.js

@@ -0,0 +1,169 @@
+import { sql } from 'drizzle-orm';
+import {
+  check,
+  date,
+  foreignKey,
+  integer,
+  jsonb,
+  pgTable,
+  text,
+  timestamp,
+  unique,
+  uuid,
+} from 'drizzle-orm/pg-core';
+
+// Every table except `organisations` carries `organisation_id`. Child rows
+// point at their parent through (organisation_id, id), so the database itself
+// refuses a row that joins two organisations. Money is integer cents.
+
+const id = () => uuid('id').primaryKey().defaultRandom();
+const organisationId = () => uuid('organisation_id').notNull();
+const createdAt = () => timestamp('created_at', { withTimezone: true }).notNull().defaultNow();
+const updatedAt = () => timestamp('updated_at', { withTimezone: true }).notNull().defaultNow();
+
+export const TAX_CODES = ['GST', 'GST_FREE'];
+export const CONTACT_KINDS = ['customer', 'supplier'];
+export const INVOICE_STATUSES = ['draft', 'issued', 'void'];
+
+export const organisations = pgTable('organisations', {
+  id: id(),
+  name: text('name').notNull(),
+  invoicePrefix: text('invoice_prefix').notNull().default('INV-'),
+  nextInvoiceNumber: integer('next_invoice_number').notNull().default(1),
+  createdAt: createdAt(),
+}, (t) => [
+  check('organisations_next_invoice_number_positive', sql`${t.nextInvoiceNumber} > 0`),
+]);
+
+export const contacts = pgTable('contacts', {
+  id: id(),
+  organisationId: organisationId().references(() => organisations.id),
+  kind: text('kind').notNull(),
+  name: text('name').notNull(),
+  email: text('email'),
+  createdAt: createdAt(),
+}, (t) => [
+  unique('contacts_org_id').on(t.organisationId, t.id),
+  unique('contacts_org_kind_name').on(t.organisationId, t.kind, t.name),
+  check('contacts_kind_valid', sql`${t.kind} in ('customer', 'supplier')`),
+]);
+
+export const priceItems = pgTable('price_items', {
+  id: id(),
+  organisationId: organisationId().references(() => organisations.id),
+  code: text('code').notNull(),
+  name: text('name').notNull(),
+  unitAmountCents: integer('unit_amount_cents').notNull(),
+  taxCode: text('tax_code').notNull().default('GST'),
+  archivedAt: timestamp('archived_at', { withTimezone: true }),
+  createdAt: createdAt(),
+}, (t) => [
+  unique('price_items_org_id').on(t.organisationId, t.id),
+  unique('price_items_org_code').on(t.organisationId, t.code),
+  check('price_items_tax_code_valid', sql`${t.taxCode} in ('GST', 'GST_FREE')`),
+]);
+
+export const invoices = pgTable('invoices', {
+  id: id(),
+  organisationId: organisationId().references(() => organisations.id),
+  contactId: uuid('contact_id').notNull(),
+  // Assigned when the invoice is first issued; kept by every later version.
+  number: text('number'),
+  status: text('status').notNull().default('draft'),
+  // The last version a customer was sent; 0 while the invoice was never issued.
+  issuedVersion: integer('issued_version').notNull().default(0),
+  reference: text('reference'),
+  currency: text('currency').notNull().default('AUD'),
+  issueDate: date('issue_date'),
+  dueDate: date('due_date'),
+  subtotalCents: integer('subtotal_cents').notNull().default(0),
+  taxCents: integer('tax_cents').notNull().default(0),
+  totalCents: integer('total_cents').notNull().default(0),
+  createdAt: createdAt(),
+  updatedAt: updatedAt(),
+}, (t) => [
+  unique('invoices_org_id').on(t.organisationId, t.id),
+  unique('invoices_org_number').on(t.organisationId, t.number),
+  foreignKey({
+    name: 'invoices_contact_same_org',
+    columns: [t.organisationId, t.contactId],
+    foreignColumns: [contacts.organisationId, contacts.id],
+  }),
+  check('invoices_status_valid', sql`${t.status} in ('draft', 'issued', 'void')`),
+  check('invoices_issued_has_number', sql`${t.status} = 'draft' or ${t.number} is not null`),
+]);
+
+export const invoiceLines = pgTable('invoice_lines', {
+  id: id(),
+  organisationId: organisationId(),
+  invoiceId: uuid('invoice_id').notNull(),
+  position: integer('position').notNull(),
+  priceItemId: uuid('price_item_id'),
+  description: text('description').notNull(),
+  quantity: integer('quantity').notNull(),
+  unitAmountCents: integer('unit_amount_cents').notNull(),
+  taxCode: text('tax_code').notNull(),
+  lineAmountCents: integer('line_amount_cents').notNull(),
+  taxCents: integer('tax_cents').notNull(),
+}, (t) => [
+  unique('invoice_lines_invoice_position').on(t.invoiceId, t.position),
+  foreignKey({
+    name: 'invoice_lines_invoice_same_org',
+    columns: [t.organisationId, t.invoiceId],
+    foreignColumns: [invoices.organisationId, invoices.id],
+  }).onDelete('cascade'),
+  foreignKey({
+    name: 'invoice_lines_price_item_same_org',
+    columns: [t.organisationId, t.priceItemId],
+    foreignColumns: [priceItems.organisationId, priceItems.id],
+  }),
+  check('invoice_lines_quantity_positive', sql`${t.quantity} > 0`),
+  check('invoice_lines_tax_code_valid', sql`${t.taxCode} in ('GST', 'GST_FREE')`),
+]);
+
+// What the customer was sent, exactly. Rows are append-only: a trigger in
+// the migrations refuses UPDATE and DELETE.
+export const invoiceVersions = pgTable('invoice_versions', {
+  id: id(),
+  organisationId: organisationId(),
+  invoiceId: uuid('invoice_id').notNull(),
+  version: integer('version').notNull(),
+  issuedAt: timestamp('issued_at', { withTimezone: true }).notNull().defaultNow(),
+  issuedBy: text('issued_by').notNull(),
+  document: jsonb('document').notNull(),
+}, (t) => [
+  unique('invoice_versions_invoice_version').on(t.invoiceId, t.version),
+  foreignKey({
+    name: 'invoice_versions_invoice_same_org',
+    columns: [t.organisationId, t.invoiceId],
+    foreignColumns: [invoices.organisationId, invoices.id],
+  }),
+  check('invoice_versions_version_positive', sql`${t.version} > 0`),
+]);
+
+export const PERSON_ROLES = ['owner', 'admin', 'staff'];
+export const PERSON_STATUSES = ['active', 'pending', 'disabled'];
+
+// Who may sign in to this installation, and with which role. Clerk proves who
+// someone is; this table decides what they may do. One installation serves one
+// lab, so people are installation-wide and carry no organisation_id. Emails
+// are stored lower-case. `clerk_user_id` is set on the person's first verified
+// sign-in; until then the row is an invitation.
+export const people = pgTable('people', {
+  id: id(),
+  email: text('email').notNull(),
+  name: text('name'),
+  role: text('role').notNull(),
+  status: text('status').notNull().default('active'),
+  clerkUserId: text('clerk_user_id'),
+  invitedBy: uuid('invited_by').references(() => people.id, { onDelete: 'set null' }),
+  linkedAt: timestamp('linked_at', { withTimezone: true }),
+  createdAt: createdAt(),
+  updatedAt: updatedAt(),
+}, (t) => [
+  unique('people_email').on(t.email),
+  unique('people_clerk_user_id').on(t.clerkUserId),
+  check('people_email_lower', sql`${t.email} = lower(${t.email})`),
+  check('people_role_valid', sql`${t.role} in ('owner', 'admin', 'staff')`),
+  check('people_status_valid', sql`${t.status} in ('active', 'pending', 'disabled')`),
+]);

package/server/deployed-build.js

@@ -0,0 +1,20 @@
+// What build is running, for GET /health: the git commit (FLOW_REVISION),
+// and on a Replit deployment the ref it was fetched as and where it came from
+// ("github", or "workspace" for an emergency build), and whether its GitHub CI
+// passed before it was built ("passed", or "unchecked" when an emergency
+// override built it anyway), which scripts/replit-deploy.sh sets, and the
+// release tag the build is (FLOW_DEPLOYED_RELEASE from that deploy, or
+// FLOW_RELEASE, which server/flow-server.js sets for an installed npm
+// package and the Dockerfile sets for a release image), when it is one. The
+// repository is public, so none of these is a secret. Each is null when
+// unknown.
+export function deployedBuildStatus(env = process.env) {
+  const read = (value) => String(value ?? "").trim() || null;
+  return {
+    revision: read(env.FLOW_REVISION),
+    ref: read(env.FLOW_DEPLOYED_REF),
+    source: read(env.FLOW_DEPLOYED_FROM),
+    checks: read(env.FLOW_DEPLOYED_CHECKS),
+    release: read(env.FLOW_DEPLOYED_RELEASE) ?? read(env.FLOW_RELEASE),
+  };
+}

package/server/flow-server.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+// Starts Flow from an installed @arcforgelabs/flow package (the `flow-server`
+// command). A published package's version is its release (2026.10.18 or
+// 2026.10.18-beta.2), so GET /health shows it as build.release. A checkout
+// starts server/index.js (`npm start`) instead: its package.json holds the
+// upcoming version, which is not a release yet.
+import { readFileSync } from 'node:fs';
+import { parseReleaseTag } from './release-channel.js';
+
+if (!process.env.FLOW_RELEASE) {
+  const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+  const release = parseReleaseTag(version);
+  if (release) process.env.FLOW_RELEASE = release.tag;
+}
+await import('./index.js');

package/server/index.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+import { createApp } from './app.js';
+import { createClerkProxy, ensureClerkAccount, loadClerkAdapter, resolveClerkProxyPath } from './auth/clerk.js';
+import { seedFirstOwner } from './auth/people.js';
+import { createPersonAuth } from './auth/session.js';
+import { resolveSignInSettings } from './auth/settings.js';
+import { migrateDatabase, openDatabase } from './db/index.js';
+import { createUpdateChecker, UPDATE_CHECK_INTERVAL_MS } from './update-check.js';
+
+const port = Number(process.env.FLOW_PORT || process.env.PORT || 19300);
+
+// Sign-in settings first: a malformed setting stops boot before anything runs.
+let settings;
+try {
+  settings = resolveSignInSettings();
+} catch (error) {
+  console.error(`[auth] ${error.message}`);
+  process.exit(1);
+}
+
+// Flow's records live in PostgreSQL. Migrations run before the server accepts
+// requests, so a release never serves an older schema.
+const database = openDatabase();
+await migrateDatabase(database.db);
+
+let auth = null;
+if (settings.mode === 'clerk') {
+  const { keys } = settings;
+  const clerk = await loadClerkAdapter({ ...keys, authorizedParties: settings.authorizedParties });
+  const personAuth = createPersonAuth({ db: database.db, clerk, ...settings });
+  let clerkProxy = null;
+  const proxyPath = resolveClerkProxyPath(keys.proxyUrl);
+  if (proxyPath) {
+    const { clerkFrontendApiProxy } = await import('@clerk/backend/proxy');
+    clerkProxy = { path: proxyPath, handler: createClerkProxy({ proxyPath, ...keys, proxy: clerkFrontendApiProxy }) };
+  }
+  auth = { settings, clerk, personAuth, clerkProxy };
+
+  if (settings.firstOwnerEmail) {
+    const seeded = await seedFirstOwner(database.db, settings.firstOwnerEmail);
+    if (seeded) {
+      console.log(`[auth] no owner yet: invited FLOW_FIRST_OWNER_EMAIL as owner (person ${seeded.id})`);
+      await ensureClerkAccount(clerk, seeded.email).catch((error) => {
+        console.error(`[auth] could not prepare the first owner's Clerk account: ${error.message}`);
+      });
+    }
+  }
+  const ownerPaths = [
+    ...(settings.ownerGoogleDomains.length ? [`Google Workspace sign-in on ${settings.ownerGoogleDomains.join(', ')} with no password`] : []),
+    `a Clerk second factor within ${settings.ownerMfaMaxAgeMinutes} min`,
+  ];
+  console.log(`[auth] Clerk sign-in on (CLERK_SECRET_KEY, ${keys.publishableSource}); public sign-up ${settings.publicSignUp ? 'on' : 'off'}; owner actions: ${ownerPaths.join(', or ')}${proxyPath ? `; Clerk proxied at ${proxyPath}` : ''}`);
+  // Replit's managed Clerk has no MFA, so there the Google Workspace path is
+  // the only way an owner can manage people.
+  if (!settings.ownerGoogleDomains.length && (process.env.REPL_ID || process.env.REPLIT_DEPLOYMENT)) {
+    console.warn('[auth] FLOW_OWNER_GOOGLE_DOMAINS is unset: on Replit\'s managed Clerk no owner can manage people (docs/SELF_HOSTING.md, "Sign-in (Clerk)")');
+  }
+} else {
+  console.log('[auth] sign-in off (FLOW_AUTH unset): person routes answer 503');
+}
+
+// Replit puts one proxy in front of the app.
+const trustProxy = process.env.REPL_ID || process.env.REPLIT_DEPLOYMENT ? 1 : false;
+
+const updates = createUpdateChecker();
+
+createApp({ database, auth, trustProxy, updates }).listen(port, () => {
+  console.log(`[flow] listening on ${port}`);
+});
+
+// The update notice: a release build logs when a newer release is out on its
+// channel, at start and every six hours. A build that is not a release asks
+// nobody.
+async function noticeUpdate() {
+  try {
+    const status = await updates.status();
+    if (status.updateAvailable) {
+      console.log(`[flow] update available: ${status.latest} (running ${status.current}, channel ${status.channel}). Notes: ${status.releaseUrl}. How to update: ${status.upgradeUrl}`);
+    }
+  } catch (error) {
+    console.error(`[flow] update check failed: ${error?.message || error}`);
+  }
+}
+noticeUpdate();
+setInterval(noticeUpdate, UPDATE_CHECK_INTERVAL_MS).unref();

package/server/integrations/port.js

@@ -0,0 +1,84 @@
+// The integration port: the one contract between the Flow core and every
+// adapter (Seazona, Xero, and later ones). The core calls only the
+// capabilities an adapter declares, and never imports an adapter directly.
+// VISION.md, "The core and its integrations".
+
+export const CAPABILITIES = Object.freeze([
+  'pullWorkItems', // billable work since a cursor (Seazona: completed cases)
+  'pushInvoice', // send an issued invoice; the Flow record id is the idempotency key
+  'pushBill', // send an approved bill; the Flow record id is the idempotency key
+  'pullPayments', // payments since a cursor, matched to invoices and bills
+  'health', // connection state for Settings
+]);
+
+const ID_PATTERN = /^[a-z][a-z0-9-]{1,31}$/;
+
+export function defineAdapter(adapter) {
+  if (!adapter || typeof adapter !== 'object') {
+    throw new TypeError('An adapter must be an object');
+  }
+  const { id, name, bundled = false, capabilities } = adapter;
+  if (typeof id !== 'string' || !ID_PATTERN.test(id)) {
+    throw new TypeError(`Adapter id must match ${ID_PATTERN}`);
+  }
+  if (typeof name !== 'string' || name.trim() === '') {
+    throw new TypeError(`Adapter ${id} needs a name`);
+  }
+  if (!capabilities || typeof capabilities !== 'object') {
+    throw new TypeError(`Adapter ${id} declares no capabilities`);
+  }
+  for (const [key, fn] of Object.entries(capabilities)) {
+    if (!CAPABILITIES.includes(key)) {
+      throw new TypeError(`Adapter ${id} declares unknown capability ${key}`);
+    }
+    if (typeof fn !== 'function') {
+      throw new TypeError(`Adapter ${id} capability ${key} must be a function`);
+    }
+  }
+  if (typeof capabilities.health !== 'function') {
+    throw new TypeError(`Adapter ${id} must declare health`);
+  }
+  return Object.freeze({ id, name, bundled: Boolean(bundled), capabilities: Object.freeze({ ...capabilities }) });
+}
+
+export function createRegistry() {
+  const adapters = new Map();
+  const enabled = new Set();
+
+  return {
+    register(adapter) {
+      const defined = defineAdapter(adapter);
+      if (adapters.has(defined.id)) {
+        throw new Error(`Adapter ${defined.id} is already registered`);
+      }
+      adapters.set(defined.id, defined);
+      return defined;
+    },
+    enable(id) {
+      if (!adapters.has(id)) throw new Error(`No adapter ${id}`);
+      enabled.add(id);
+    },
+    disable(id) {
+      enabled.delete(id);
+    },
+    list() {
+      return [...adapters.values()].map((a) => ({
+        id: a.id,
+        name: a.name,
+        bundled: a.bundled,
+        enabled: enabled.has(a.id),
+        capabilities: Object.keys(a.capabilities),
+      }));
+    },
+    // The enabled adapters that declare one capability. The core fans out to
+    // these and nothing else, so a disabled adapter changes nothing.
+    with(capability) {
+      if (!CAPABILITIES.includes(capability)) {
+        throw new TypeError(`Unknown capability ${capability}`);
+      }
+      return [...enabled]
+        .map((id) => adapters.get(id))
+        .filter((a) => typeof a.capabilities[capability] === 'function');
+    },
+  };
+}

package/server/rate-limit.js

@@ -0,0 +1,21 @@
+// A fixed-window request limit per client address (req.ip, which honours
+// Express's `trust proxy`). In memory: one Flow process serves one lab.
+export function rateLimit({ limit, windowMs, now = Date.now }) {
+  const windows = new Map();
+  return (req, res, next) => {
+    const at = now();
+    if (windows.size > 10_000) {
+      for (const [key, entry] of windows) if (entry.resetAt <= at) windows.delete(key);
+    }
+    const key = req.ip || 'unknown';
+    let entry = windows.get(key);
+    if (!entry || entry.resetAt <= at) {
+      entry = { count: 0, resetAt: at + windowMs };
+      windows.set(key, entry);
+    }
+    entry.count += 1;
+    if (entry.count <= limit) return next();
+    res.set('Retry-After', String(Math.ceil((entry.resetAt - at) / 1000)));
+    return res.status(429).json({ ok: false, code: 'rate_limited', error: 'Too many requests. Wait and try again.' });
+  };
+}

package/server/release-channel.js

@@ -0,0 +1,146 @@
+// Which published Flow release a channel points at, read anonymously from
+// GitHub Releases (with npm's dist-tags as the fallback). Used by the Replit
+// deploy (scripts/deploy-release.js, FLOW_DEPLOY_REF=stable|beta).
+//
+// Release names follow docs/RELEASING.md: vYYYY.M.D is stable, and
+// vYYYY.M.D-beta.N is a beta of the upcoming YYYY.M.D.
+//
+//   stable  GitHub's latest release (what Flow Release Promote points at, so
+//           a rollback is followed), else npm `latest`
+//   beta    the newest release of all, betas and stable releases alike, so a
+//           beta installation is never behind stable; else npm `beta`
+//
+// Nothing here sends anything about the installation: each request is an
+// anonymous GET of public data.
+
+const TAG = /^v(20\d{2})\.([1-9]|1[0-2])\.([1-9]|[12]\d|3[01])(?:-beta\.([1-9]\d*))?$/;
+export const CHANNELS = ["stable", "beta"];
+export const DEFAULT_GITHUB_API = "https://api.github.com";
+export const DEFAULT_GITHUB_DOWNLOADS = "https://github.com";
+export const DEFAULT_NPM_REGISTRY = "https://registry.npmjs.org";
+export const DEFAULT_PACKAGE = "@arcforgelabs/flow";
+const ATTEMPTS = 3;
+const TIMEOUT_MS = 20_000;
+
+export class ReleaseUnavailable extends Error {}
+
+// { tag, version, channel, parts } for a release tag (with or without its
+// leading "v"), or null.
+export function parseReleaseTag(value) {
+  const tag = String(value ?? "").startsWith("v") ? String(value) : `v${value}`;
+  const match = TAG.exec(tag);
+  if (!match) return null;
+  const beta = match[4] ? Number(match[4]) : null;
+  return {
+    tag,
+    version: tag.slice(1),
+    channel: beta ? "beta" : "stable",
+    // A stable release sorts after every beta of its own version.
+    parts: [Number(match[1]), Number(match[2]), Number(match[3]), beta ?? Number.POSITIVE_INFINITY],
+  };
+}
+
+// Negative when a is older than b, positive when newer, 0 when the same.
+export function compareReleases(a, b) {
+  const [x, y] = [parseReleaseTag(a), parseReleaseTag(b)];
+  if (!x || !y) throw new ReleaseUnavailable(`cannot compare ${a} with ${b}`);
+  for (let index = 0; index < 4; index += 1) {
+    if (x.parts[index] !== y.parts[index]) return x.parts[index] < y.parts[index] ? -1 : 1;
+  }
+  return 0;
+}
+
+async function get(url, { fetchImpl, retryDelayMs, as = "json" }) {
+  let lastError;
+  for (let attempt = 1; attempt <= ATTEMPTS; attempt += 1) {
+    let response;
+    try {
+      response = await fetchImpl(url, {
+        headers: { accept: as === "json" ? "application/json" : "*/*", "user-agent": "flow-release-channel" },
+        signal: AbortSignal.timeout(TIMEOUT_MS),
+      });
+    } catch (error) {
+      lastError = `${new URL(url).host} did not answer (${error?.cause?.code || error?.name || "network error"})`;
+    }
+    if (response) {
+      if (response.ok) return as === "json" ? response.json() : Buffer.from(await response.arrayBuffer());
+      if ((response.status === 403 || response.status === 429) && response.headers.get("x-ratelimit-remaining") === "0") {
+        throw new ReleaseUnavailable(`GitHub's rate limit for anonymous requests is used up (${url})`);
+      }
+      lastError = `${url} answered HTTP ${response.status}`;
+      if (response.status < 500 && response.status !== 429) break;
+    }
+    if (attempt < ATTEMPTS) await new Promise((wake) => setTimeout(wake, attempt * retryDelayMs));
+  }
+  throw new ReleaseUnavailable(lastError);
+}
+
+async function fromGitHub(channel, { slug, githubApi, fetchImpl, retryDelayMs }) {
+  if (channel === "stable") {
+    const latest = await get(`${githubApi}/repos/${slug}/releases/latest`, { fetchImpl, retryDelayMs });
+    const release = parseReleaseTag(latest?.tag_name);
+    if (!release || release.channel !== "stable" || latest.prerelease || latest.draft) {
+      throw new ReleaseUnavailable(`GitHub's latest release (${latest?.tag_name}) is not a stable Flow release`);
+    }
+    return release.tag;
+  }
+  const list = await get(`${githubApi}/repos/${slug}/releases?per_page=50`, { fetchImpl, retryDelayMs });
+  const tags = (Array.isArray(list) ? list : [])
+    .filter((release) => !release.draft && parseReleaseTag(release.tag_name))
+    .map((release) => release.tag_name)
+    .sort(compareReleases);
+  if (!tags.length) throw new ReleaseUnavailable(`${slug} has no published Flow release`);
+  return tags.at(-1);
+}
+
+async function fromNpm(channel, { npmRegistry, packageName, fetchImpl, retryDelayMs }) {
+  const metadata = await get(`${npmRegistry}/${packageName.replaceAll("/", "%2f")}`, { fetchImpl, retryDelayMs });
+  const distTag = channel === "stable" ? "latest" : "beta";
+  const version = metadata?.["dist-tags"]?.[distTag];
+  const release = parseReleaseTag(version);
+  if (!release || (channel === "stable" && release.channel !== "stable")) {
+    throw new ReleaseUnavailable(`npm ${distTag} (${version}) is not a ${channel} Flow release`);
+  }
+  return release.tag;
+}
+
+// { tag, source } for the release the channel points at, or a
+// ReleaseUnavailable naming why neither GitHub nor npm could say.
+export async function resolveChannelRelease({
+  channel,
+  slug,
+  githubApi = DEFAULT_GITHUB_API,
+  npmRegistry = DEFAULT_NPM_REGISTRY,
+  packageName = DEFAULT_PACKAGE,
+  fetchImpl = fetch,
+  retryDelayMs = 2000,
+}) {
+  if (!CHANNELS.includes(channel)) throw new ReleaseUnavailable(`channel must be stable or beta, not "${channel}"`);
+  try {
+    return { tag: await fromGitHub(channel, { slug, githubApi, fetchImpl, retryDelayMs }), source: "github" };
+  } catch (github) {
+    if (!(github instanceof ReleaseUnavailable)) throw github;
+    try {
+      return { tag: await fromNpm(channel, { npmRegistry, packageName, fetchImpl, retryDelayMs }), source: "npm", githubError: github.message };
+    } catch (npm) {
+      if (!(npm instanceof ReleaseUnavailable)) throw npm;
+      throw new ReleaseUnavailable(`GitHub: ${github.message}; npm: ${npm.message}`);
+    }
+  }
+}
+
+// The release's manifest, checked against its .sha256: { commit, version,
+// manifestSha256 }.
+export async function verifyReleaseManifest({ slug, tag, githubDownloads = DEFAULT_GITHUB_DOWNLOADS, fetchImpl = fetch, retryDelayMs = 2000 }) {
+  const { createHash } = await import("node:crypto");
+  const base = `${githubDownloads}/${slug}/releases/download/${tag}`;
+  const bytes = await get(`${base}/release-manifest.json`, { fetchImpl, retryDelayMs, as: "bytes" });
+  const sidecar = (await get(`${base}/release-manifest.json.sha256`, { fetchImpl, retryDelayMs, as: "bytes" })).toString("utf8");
+  const sha256 = createHash("sha256").update(bytes).digest("hex");
+  if (sidecar.trim().split(/\s+/)[0] !== sha256) throw new ReleaseUnavailable(`${tag}'s release-manifest.json does not match its .sha256`);
+  const manifest = JSON.parse(bytes.toString("utf8"));
+  if (manifest.tag !== tag || !/^[0-9a-f]{40}$/.test(String(manifest.commit))) {
+    throw new ReleaseUnavailable(`${tag}'s release-manifest.json does not describe ${tag}`);
+  }
+  return { commit: manifest.commit, version: manifest.version, manifestSha256: sha256 };
+}

package/server/update-check.js

@@ -0,0 +1,84 @@
+// Is a newer Flow release out? GET /api/updates answers, and the server logs
+// a notice when one is (server/index.js).
+//
+// Flow knows its own release from GET /health's build.release
+// (server/deployed-build.js): the tag a Replit deploy of a channel or a pinned
+// release resolved to, a release image's FLOW_RELEASE, or an installed npm
+// package's version (server/flow-server.js). A build that is not a release (a checkout of main, a CI
+// image) has none, so it is never told to update and asks nobody.
+//
+// The channel is the one the installation follows: FLOW_UPDATE_CHANNEL when
+// set, else FLOW_DEPLOYED_REF when that is stable or beta, else beta for a
+// beta release, else stable. The newest release on that channel comes from
+// server/release-channel.js: an anonymous GET of public data on GitHub, or
+// npm. Nothing about the installation is sent. The answer, or the reason
+// there is none, is cached and asked again at most every six hours.
+// FLOW_UPDATE_CHECK=off turns the check off.
+import { deployedBuildStatus } from "./deployed-build.js";
+import { CHANNELS, compareReleases, parseReleaseTag, resolveChannelRelease } from "./release-channel.js";
+
+export const UPDATE_CHECK_INTERVAL_MS = 6 * 60 * 60 * 1000;
+export const FLOW_REPOSITORY = "arcforgelabs/flow";
+
+export function updateChannel(env = process.env, current = null) {
+  const pick = (value) => (CHANNELS.includes(String(value ?? "").trim()) ? String(value).trim() : null);
+  return pick(env.FLOW_UPDATE_CHANNEL) || pick(env.FLOW_DEPLOYED_REF) || (parseReleaseTag(current)?.channel === "beta" ? "beta" : "stable");
+}
+
+export function updateCheckEnabled(env = process.env) {
+  return !["off", "0", "false", "no"].includes(String(env.FLOW_UPDATE_CHECK ?? "").trim().toLowerCase());
+}
+
+// Where an operator reads how to move their installation to a release.
+export function upgradeGuideUrl(env = process.env) {
+  const doc = env.FLOW_RUNTIME === "replit" ? "docs/REPLIT.md#following-stable-releases" : "docs/SELF_HOSTING.md";
+  return `https://github.com/${FLOW_REPOSITORY}/blob/main/${doc}`;
+}
+
+export function createUpdateChecker({
+  env = process.env,
+  fetchImpl = fetch,
+  now = () => Date.now(),
+  intervalMs = UPDATE_CHECK_INTERVAL_MS,
+  resolve = resolveChannelRelease,
+} = {}) {
+  let cache = null; // { channel, checkedAt, latest, error }
+  let inflight = null;
+
+  async function refresh(channel) {
+    const checkedAt = now();
+    try {
+      const { tag } = await resolve({ channel, slug: FLOW_REPOSITORY, fetchImpl, retryDelayMs: 500 });
+      cache = { channel, checkedAt, latest: tag, error: null };
+    } catch (error) {
+      // A failed check waits out the interval too, so an unreachable GitHub
+      // is not asked on every page load.
+      cache = { channel, checkedAt, latest: null, error: error?.message || String(error) };
+    }
+    return cache;
+  }
+
+  return {
+    /** The update status; `enabled` false (or FLOW_UPDATE_CHECK=off) asks nobody. */
+    async status({ enabled = updateCheckEnabled(env) } = {}) {
+      const current = deployedBuildStatus(env).release;
+      const channel = updateChannel(env, current);
+      const base = { enabled, channel, current, latest: null, updateAvailable: false, checkedAt: null, error: null, releaseUrl: null, upgradeUrl: upgradeGuideUrl(env) };
+      if (!enabled || !parseReleaseTag(current)) return base;
+      if (!cache || cache.channel !== channel || now() - cache.checkedAt >= intervalMs) {
+        inflight ??= refresh(channel).finally(() => { inflight = null; });
+        await inflight;
+      }
+      const { latest, error, checkedAt } = cache;
+      const updateAvailable = Boolean(latest) && compareReleases(latest, current) > 0;
+      return {
+        ...base,
+        latest,
+        updateAvailable,
+        checkedAt: new Date(checkedAt).toISOString(),
+        error,
+        releaseUrl: updateAvailable ? `https://github.com/${FLOW_REPOSITORY}/releases/tag/${latest}` : null,
+      };
+    },
+  };
+}