@arcforgelabs/flow 2026.10.18 → 2026.10.19

package/README.md

@@ -33,6 +33,9 @@ run a lab.
 | `docs/RELEASING.md` | Versions and channels, the release workflows, how to cut and roll back a release, and the one-time setup |
 | `docs/SELF_HOSTING.md` | Running a Flow release with Docker, Node or Replit, the update notice, and Clerk sign-in |
 | `docs/REPLIT.md` | A Replit workspace of this repository that follows a release channel (`FLOW_DEPLOY_REF`) |
+| `docs/INTEGRATIONS.md` | How an integration adapter is built, turned on and off, and owns its tables |
+| `docs/XERO.md` | The Xero adapter: modes, settings, rate limits, connecting Xero and draft invoices |
+| `docs/SEAZONA.md` | The Seazona adapter: modes, settings, the rate governor, replay files and its tables |
 | `server/integrations/port.js` | The integration port every adapter implements |
 
 ## Getting started

package/SECURITY.md

@@ -46,7 +46,10 @@ paste a credential, in full or in part.
   Secrets), never in the repository, a log, an issue or a pull request. Name
   the variable, never its value.
 - No account has a built-in or fallback password, in any environment.
-- Sign-in, API and integration routes are rate limited.
+- Sign-in, API and integration routes are rate limited per client
+  (`server/rate-limit.js`): the sign-in page and its config 30 requests a
+  minute, `/api` 120, and the Clerk proxy 300. A client over the limit gets
+  `429` with `Retry-After`.
 - Session cookies are `Secure`, `HttpOnly` and `SameSite`.
 - Flow stores no clinical notes, images or scans, and keeps a patient
   reference only where an invoice must print one.

package/npm-shrinkwrap.json

@@ -1,21 +1,22 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.10.18",
+  "version": "2026.10.19",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@arcforgelabs/flow",
-      "version": "2026.10.18",
+      "version": "2026.10.19",
       "license": "MIT",
       "dependencies": {
         "@clerk/backend": "3.23.2",
         "drizzle-orm": "0.45.3",
         "express": "5.3.0",
+        "express-rate-limit": "8.7.0",
         "pg": "8.23.1"
       },
       "bin": {
-        "flow-server": "server/index.js"
+        "flow-server": "server/flow-server.js"
       },
       "devDependencies": {
         "drizzle-kit": "0.31.11"
@@ -1431,6 +1432,25 @@
         "url": "https://opencollective.com/express"
       }
     },
+    "node_modules/express-rate-limit": {
+      "version": "8.7.0",
+      "resolved": "https://registry.npmjs.org/express-rate-limit/-/express-rate-limit-8.7.0.tgz",
+      "integrity": "sha512-hOwV7WOxXfjRpAM1DSJWZDXx3GhplwD8IfwuwvogD8i1Qnkgosw/H45s4ZnFAUHDAhPjlY9hLBvJhKmGMyY26g==",
+      "license": "MIT",
+      "dependencies": {
+        "debug": "^4.4.3",
+        "ip-address": "^10.2.0"
+      },
+      "engines": {
+        "node": ">= 16"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/express-rate-limit"
+      },
+      "peerDependencies": {
+        "express": ">= 4.11"
+      }
+    },
     "node_modules/fast-sha256": {
       "version": "1.3.0",
       "resolved": "https://registry.npmjs.org/fast-sha256/-/fast-sha256-1.3.0.tgz",
@@ -1634,6 +1654,15 @@
       "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==",
       "license": "ISC"
     },
+    "node_modules/ip-address": {
+      "version": "10.7.3",
+      "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.7.3.tgz",
+      "integrity": "sha512-A1kdq/tSb5QjvKvAMgIoEvDBIgL7qaqVP/jkvSwYYRZ9iEzvPpopxp2wQfu3SuZRHtpHNxMn8Fs0bS+gf5Xmwg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 12"
+      }
+    },
     "node_modules/ipaddr.js": {
       "version": "1.9.1",
       "resolved": "https://registry.npmjs.org/ipaddr.js/-/ipaddr.js-1.9.1.tgz",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.10.18",
+  "version": "2026.10.19",
   "description": "Invoicing, bill entry and a financial dashboard for labs, with Seazona and Xero integrations.",
   "license": "MIT",
   "repository": {
@@ -30,13 +30,14 @@
   },
   "scripts": {
     "start": "node server/index.js",
-    "test": "node --test test/*.test.js",
+    "test": "node --test --test-concurrency=1 test/*.test.js",
     "db:generate": "drizzle-kit generate"
   },
   "dependencies": {
     "@clerk/backend": "3.23.2",
     "drizzle-orm": "0.45.3",
     "express": "5.3.0",
+    "express-rate-limit": "8.7.0",
     "pg": "8.23.1"
   },
   "devDependencies": {

package/server/app.js

@@ -2,6 +2,7 @@ import express from 'express';
 import { createConnectorApi } from './api/connector.js';
 import { createSignInRouter } from './auth/routes.js';
 import { deployedBuildStatus } from './deployed-build.js';
+import { integrationsHealth } from './integrations/health.js';
 import { rateLimit } from './rate-limit.js';
 
 // The Flow HTTP app. Routes are added per module (invoices, bills, payments,
@@ -10,15 +11,25 @@ import { rateLimit } from './rate-limit.js';
 // `auth` is { settings, clerk, personAuth, clerkProxy } from server/index.js
 // (or a test). Without it sign-in is off and every person route answers 503.
 // `trustProxy` is Express's `trust proxy`: 1 hop on Replit, so rate limits
-// count per client rather than per proxy. `build` is what GET /health reports
+// count per client rather than per proxy. The limits are requests per minute
+// per client, sized for a lab of a few people: `rateLimitPerMinute` for /api,
+// `signInRateLimitPerMinute` for the sign-in page and its config, and
+// `clerkProxyRateLimitPerMinute` for Clerk's Frontend API, which a signed-in
+// browser calls often. `build` is what GET /health reports
 // (server/deployed-build.js); `updates` is a server/update-check.js checker.
+// `integrations` is the started registry (server/integrations/index.js); each
+// adapter's own routes are mounted under /api/<id>, and GET /health reports
+// each one (server/integrations/health.js).
 export function createApp({
   build = deployedBuildStatus(),
   database = null,
   auth = null,
   updates = null,
+  integrations = null,
   trustProxy = false,
   rateLimitPerMinute = 120,
+  signInRateLimitPerMinute = 30,
+  clerkProxyRateLimitPerMinute = 300,
   log = console,
 } = {}) {
   const app = express();
@@ -34,12 +45,19 @@ export function createApp({
     // The running build (commit, deploy ref, source, CI result, release), so
     // an operator can confirm what a publish deployed. The repository is
     // public, so none of it is a secret.
-    res.status(ok ? 200 : 503).json({ ok, service: 'flow', database: databaseOk, build });
+    // Each integration's state and its own health (mode, freshness, failing
+    // records). An integration problem does not fail the health check: Flow's
+    // core works with no integration connected (VISION.md).
+    const body = { ok, service: 'flow', database: databaseOk, build };
+    if (integrations) body.integrations = await integrationsHealth(integrations);
+    res.status(ok ? 200 : 503).json(body);
   });
 
   // Clerk's Frontend API through Flow's origin (CLERK_PROXY_URL). Before any
   // body parser, so request bodies reach Clerk intact.
-  if (auth?.clerkProxy) app.use(auth.clerkProxy.path, auth.clerkProxy.handler);
+  if (auth?.clerkProxy) {
+    app.use(auth.clerkProxy.path, rateLimit({ limit: clerkProxyRateLimitPerMinute, windowMs: 60_000 }), auth.clerkProxy.handler);
+  }
 
   app.use('/api', rateLimit({ limit: rateLimitPerMinute, windowMs: 60_000 }));
 
@@ -64,11 +82,16 @@ export function createApp({
     }
   }
 
+  for (const { path, handler } of integrations?.routes({ db: database?.db ?? null, personAuth: auth?.personAuth ?? null, log }) ?? []) {
+    app.use(path, handler);
+  }
+
   app.use(createSignInRouter({
     settings: auth?.settings ?? { mode: 'off' },
     db: database?.db ?? null,
     clerk: auth?.clerk ?? null,
     personAuth: auth?.personAuth ?? null,
+    rateLimitPerMinute: signInRateLimitPerMinute,
     log,
   }));
 

package/server/auth/routes.js

@@ -1,6 +1,7 @@
 import { fileURLToPath } from 'node:url';
 import express from 'express';
 import { FlowError } from '../core/errors.js';
+import { rateLimit } from '../rate-limit.js';
 import { ensureClerkAccount } from './clerk.js';
 import {
   findPersonByEmail,
@@ -17,14 +18,23 @@ const signInPage = fileURLToPath(new URL('./sign-in.html', import.meta.url));
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const ERROR_STATUS = { invalid: 400, forbidden: 403, not_found: 404, conflict: 409 };
 
-// The Clerk script the sign-in page loads: through Flow's own origin when
+// The Clerk scripts the sign-in page loads: through Flow's own origin when
 // CLERK_PROXY_URL is set, otherwise from the Clerk instance's Frontend API
-// (its host is encoded in the publishable key).
-export function clerkScriptUrl({ publishableKey, proxyUrl }) {
-  const base = proxyUrl
+// (its host is encoded in the publishable key). clerk-js 6 ships without its
+// prebuilt components; the sign-in widget comes from @clerk/ui, passed to
+// Clerk.load().
+function clerkScriptBase({ publishableKey, proxyUrl }) {
+  return proxyUrl
     ? proxyUrl.replace(/\/+$/, '')
     : `https://${Buffer.from(publishableKey.split('_')[2] ?? '', 'base64').toString('utf8').replace(/\$$/, '')}`;
-  return `${base}/npm/@clerk/clerk-js@6/dist/clerk.browser.js`;
+}
+
+export function clerkScriptUrl(keys) {
+  return `${clerkScriptBase(keys)}/npm/@clerk/clerk-js@6/dist/clerk.browser.js`;
+}
+
+export function clerkUiScriptUrl(keys) {
+  return `${clerkScriptBase(keys)}/npm/@clerk/ui@1/dist/ui.browser.js`;
 }
 
 function sendError(res, error, log) {
@@ -36,28 +46,33 @@ function sendError(res, error, log) {
 }
 
 // Sign-in routes. `settings` comes from resolveSignInSettings; with sign-in
-// off, person routes answer 503 and nothing else is mounted.
-export function createSignInRouter({ settings, db, clerk, personAuth, log = console }) {
+// off, person routes answer 503 and nothing else is mounted. The sign-in page
+// and its config have their own limit per client (`rateLimitPerMinute`);
+// /api/me and /api/people sit under the app's /api limit as well.
+export function createSignInRouter({ settings, db, clerk, personAuth, rateLimitPerMinute = 30, log = console }) {
   const router = express.Router();
   const signInOn = settings.mode === 'clerk';
+  const signInLimit = rateLimit({ limit: rateLimitPerMinute, windowMs: 60_000 });
 
   // Public: what the sign-in page needs. The publishable key is meant for
   // browsers. Served at runtime, so one build serves Replit's development
   // and production Clerk instances.
-  router.get('/api/auth/config', (_req, res) => {
+  router.get('/api/auth/config', signInLimit, (_req, res) => {
     res.set('Cache-Control', 'no-store');
     if (!signInOn) return res.json({ ok: true, mode: 'off' });
     const { publishableKey, proxyUrl } = settings.keys;
     return res.json({
       ok: true,
       mode: 'clerk',
-      publicSignUp: settings.publicSignUp,
-      clerk: { publishableKey, proxyUrl, scriptUrl: clerkScriptUrl(settings.keys) },
+      // The widget creates Clerk accounts only when someone could ask for
+      // access; Flow still refuses an email outside FLOW_SIGN_UP_DOMAINS.
+      publicSignUp: settings.publicSignUp || Boolean(settings.signUpDomains?.length),
+      clerk: { publishableKey, proxyUrl, scriptUrl: clerkScriptUrl(settings.keys), uiScriptUrl: clerkUiScriptUrl(settings.keys) },
     });
   });
 
-  router.get('/', (_req, res) => res.redirect(302, '/sign-in'));
-  router.get('/sign-in', (_req, res) => {
+  router.get('/', signInLimit, (_req, res) => res.redirect(302, '/sign-in'));
+  router.get('/sign-in', signInLimit, (_req, res) => {
     res.set('Cache-Control', 'no-store');
     res.set('X-Frame-Options', 'DENY');
     res.sendFile(signInPage);

package/server/auth/session.js

@@ -46,6 +46,7 @@ export function createPersonAuth({
   db,
   clerk,
   publicSignUp = false,
+  signUpDomains = [],
   ownerGoogleDomains = [],
   ownerMfaMaxAgeMinutes = DEFAULT_OWNER_MFA_MAX_AGE_MINUTES,
   log = console,
@@ -81,9 +82,11 @@ export function createPersonAuth({
       return again ? { person: again } : { denial: 'email_linked_elsewhere' };
     }
 
-    // Someone Flow does not know. With public sign-up off Flow records
-    // nothing about them: they simply have no access.
-    if (!publicSignUp) {
+    // Someone Flow does not know. Unless public sign-up is on or their
+    // email's domain may sign up, Flow records nothing about them: they
+    // simply have no access.
+    const domain = email.slice(email.lastIndexOf('@') + 1);
+    if (!publicSignUp && !signUpDomains.includes(domain)) {
       log.warn?.(`[auth] Clerk user ${clerkUserId} refused: not invited`);
       return { denial: 'not_invited' };
     }

package/server/auth/settings.js

@@ -64,24 +64,42 @@ export function parseOwnerMfaMaxAge(raw) {
   return minutes;
 }
 
-// FLOW_OWNER_GOOGLE_DOMAINS: comma-separated email domains whose Google
-// Workspace sign-in counts as an owner's verified sign-in (that Workspace
-// enforces 2-Step Verification). No default: unset turns that path off.
-export function parseOwnerGoogleDomains(raw) {
+function parseDomains(raw, name) {
   const domains = String(raw ?? '').split(',').map((part) => part.trim().toLowerCase()).filter(Boolean);
   for (const domain of domains) {
     if (!/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+$/.test(domain)) {
-      throw new Error('FLOW_OWNER_GOOGLE_DOMAINS must be a comma-separated list of email domains (e.g. example.com)');
+      throw new Error(`${name} must be a comma-separated list of email domains (e.g. example.com)`);
     }
   }
   return [...new Set(domains)];
 }
 
+// FLOW_OWNER_GOOGLE_DOMAINS: comma-separated email domains whose Google
+// Workspace sign-in counts as an owner's verified sign-in (that Workspace
+// enforces 2-Step Verification). No default: unset turns that path off.
+export function parseOwnerGoogleDomains(raw) {
+  return parseDomains(raw, 'FLOW_OWNER_GOOGLE_DOMAINS');
+}
+
+// FLOW_SIGN_UP_DOMAINS: comma-separated email domains whose people may ask
+// for access without an invitation. They wait as `pending` until an owner
+// approves them; everyone else still needs an invitation. Unset: none.
+export function parseSignUpDomains(raw) {
+  return parseDomains(raw, 'FLOW_SIGN_UP_DOMAINS');
+}
+
 // FLOW_PUBLIC_ORIGIN: the published app's origin. Clerk then accepts only
-// session tokens minted for it. Unset: Clerk's default.
+// session tokens minted for it. Unset: Clerk's default. A Replit workspace
+// shares its secrets with the published app, so there its own development
+// address (REPLIT_DEV_DOMAIN, never set on the published app) is accepted too.
 export function resolveAuthorizedParties(env = process.env) {
   const raw = readEnv(env, 'FLOW_PUBLIC_ORIGIN');
   if (!raw) return [];
+  const devDomain = readEnv(env, 'REPLIT_DEPLOYMENT') ? '' : readEnv(env, 'REPLIT_DEV_DOMAIN');
+  return [publicOrigin(raw), ...(devDomain ? [`https://${devDomain}`] : [])];
+}
+
+function publicOrigin(raw) {
   let url;
   try {
     url = new URL(raw);
@@ -91,7 +109,7 @@ export function resolveAuthorizedParties(env = process.env) {
   if (url.protocol !== 'https:' && url.protocol !== 'http:') {
     throw new Error('FLOW_PUBLIC_ORIGIN must be an http(s) URL');
   }
-  return [url.origin];
+  return url.origin;
 }
 
 // FLOW_FIRST_OWNER_EMAIL: while the installation has no owner, Flow invites
@@ -116,6 +134,7 @@ export function resolveSignInSettings(env = process.env) {
     mode,
     keys: resolveClerkKeys(env),
     publicSignUp: resolvePublicSignUp(env),
+    signUpDomains: parseSignUpDomains(readEnv(env, 'FLOW_SIGN_UP_DOMAINS')),
     ownerMfaMaxAgeMinutes: parseOwnerMfaMaxAge(readEnv(env, 'FLOW_OWNER_MFA_MAX_AGE')),
     ownerGoogleDomains: parseOwnerGoogleDomains(readEnv(env, 'FLOW_OWNER_GOOGLE_DOMAINS')),
     authorizedParties: resolveAuthorizedParties(env),

package/server/auth/sign-in.html

@@ -60,7 +60,7 @@ if (!config || config.mode !== 'clerk') {
 } else {
   await loadClerk(config.clerk);
   const Clerk = window.Clerk;
-  await Clerk.load();
+  await Clerk.load({ ui: { ClerkUI: window.__internal_ClerkUICtor } });
   Clerk.addListener(({ user }) => { if (user && $('signed-in').hidden) showSignedIn(); });
   if (Clerk.user) {
     await showSignedIn();
@@ -78,15 +78,26 @@ if (!config || config.mode !== 'clerk') {
   }
 }
 
-function loadClerk({ publishableKey, proxyUrl, scriptUrl }) {
+// clerk-js, then its prebuilt components (@clerk/ui), which set
+// window.__internal_ClerkUICtor for Clerk.load().
+function loadClerk({ publishableKey, proxyUrl, scriptUrl, uiScriptUrl }) {
+  return Promise.all([
+    loadScript(scriptUrl, (script) => {
+      script.dataset.clerkPublishableKey = publishableKey;
+      if (proxyUrl) script.dataset.clerkProxyUrl = proxyUrl;
+    }),
+    loadScript(uiScriptUrl),
+  ]);
+}
+
+function loadScript(src, prepare = () => {}) {
   return new Promise((resolve, reject) => {
     const script = document.createElement('script');
-    script.src = scriptUrl;
+    script.src = src;
     script.crossOrigin = 'anonymous';
-    script.dataset.clerkPublishableKey = publishableKey;
-    if (proxyUrl) script.dataset.clerkProxyUrl = proxyUrl;
+    prepare(script);
     script.onload = resolve;
-    script.onerror = () => { status('Could not load sign-in. Try again shortly.', true); reject(new Error('clerk-js')); };
+    script.onerror = () => { status('Could not load sign-in. Try again shortly.', true); reject(new Error(src)); };
     document.head.append(script);
   });
 }

package/server/core/invoices.js

@@ -107,7 +107,10 @@ export async function issueInvoice(db, organisationId, invoiceId, { issuedBy, is
   return db.transaction(async (tx) => {
     const invoice = await loadInvoice(tx, organisationId, invoiceId, { lock: true });
     if (invoice.status !== 'draft') throw new FlowError('not_draft', 'only a draft invoice can be issued');
-    const lines = await tx.select().from(invoiceLines)
+    // Each line with its price item's code, so the document says which item
+    // was sold even if the price list changes later.
+    const lines = await tx.select({ line: invoiceLines, itemCode: priceItems.code }).from(invoiceLines)
+      .leftJoin(priceItems, eq(priceItems.id, invoiceLines.priceItemId))
       .where(eq(invoiceLines.invoiceId, invoice.id)).orderBy(asc(invoiceLines.position));
     if (!lines.length) throw new FlowError('invalid', 'an invoice needs at least one line');
 
@@ -129,8 +132,8 @@ export async function issueInvoice(db, organisationId, invoiceId, { issuedBy, is
       reference: invoice.reference,
       currency: invoice.currency,
       contact: { id: contact.id, name: contact.name, email: contact.email },
-      lines: lines.map(({ position, description, quantity, unitAmountCents, taxCode, lineAmountCents, taxCents }) => (
-        { position, description, quantity, unitAmountCents, taxCode, lineAmountCents, taxCents }
+      lines: lines.map(({ line: { position, description, quantity, unitAmountCents, taxCode, lineAmountCents, taxCents }, itemCode }) => (
+        { position, itemCode: itemCode ?? null, description, quantity, unitAmountCents, taxCode, lineAmountCents, taxCents }
       )),
       subtotalCents: invoice.subtotalCents,
       taxCents: invoice.taxCents,