@arcforgelabs/flow 0.0.0-stage → 2026.10.18-beta.1

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2026.10.18-beta.1",
+  "description": "Invoicing, bill entry and a financial dashboard for labs, with Seazona and Xero integrations.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arcforgelabs/flow.git"
+  },
+  "homepage": "https://github.com/arcforgelabs/flow#readme",
+  "bugs": {
+    "url": "https://github.com/arcforgelabs/flow/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "flow-server": "./server/flow-server.js"
+  },
+  "files": [
+    "server/",
+    "SECURITY.md",
+    "VISION.md",
+    "npm-shrinkwrap.json"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "start": "node server/index.js",
+    "test": "node --test test/*.test.js",
+    "db:generate": "drizzle-kit generate"
+  },
+  "dependencies": {
+    "@clerk/backend": "3.23.2",
+    "drizzle-orm": "0.45.3",
+    "express": "5.3.0",
+    "pg": "8.23.1"
+  },
+  "devDependencies": {
+    "drizzle-kit": "0.31.11"
+  }
+}

package/server/api/connector.js

@@ -0,0 +1,17 @@
+import express from 'express';
+
+// The Flow API (`/api/flow/v1`, issue #9) is for scripts, the `flow` CLI and
+// outside agents. Callers authenticate with a signed connector key, never a
+// Clerk session: sign-in and machine access stay separate. Nothing here reads
+// a Clerk session. Until connector keys exist, every request is refused.
+export function createConnectorApi() {
+  const router = express.Router();
+  router.use((_req, res) => {
+    res.status(401).json({
+      ok: false,
+      code: 'connector_signature_required',
+      error: 'The Flow API needs a signed connector request. Connector keys are not available yet.',
+    });
+  });
+  return router;
+}

package/server/app.js

@@ -0,0 +1,76 @@
+import express from 'express';
+import { createConnectorApi } from './api/connector.js';
+import { createSignInRouter } from './auth/routes.js';
+import { deployedBuildStatus } from './deployed-build.js';
+import { rateLimit } from './rate-limit.js';
+
+// The Flow HTTP app. Routes are added per module (invoices, bills, payments,
+// dashboard).
+//
+// `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
+// (server/deployed-build.js); `updates` is a server/update-check.js checker.
+export function createApp({
+  build = deployedBuildStatus(),
+  database = null,
+  auth = null,
+  updates = null,
+  trustProxy = false,
+  rateLimitPerMinute = 120,
+  log = console,
+} = {}) {
+  const app = express();
+  app.disable('x-powered-by');
+  app.set('trust proxy', trustProxy);
+
+  app.get('/health', async (_req, res) => {
+    let databaseOk = null;
+    if (database) {
+      databaseOk = await database.pool.query('SELECT 1').then(() => true, () => false);
+    }
+    const ok = databaseOk !== false;
+    // 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 });
+  });
+
+  // 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);
+
+  app.use('/api', rateLimit({ limit: rateLimitPerMinute, windowMs: 60_000 }));
+
+  // Machine access first, with its own authentication (issue #9). A Clerk
+  // session never opens it.
+  app.use('/api/flow/v1', createConnectorApi());
+
+  // Is a newer Flow release out on this installation's channel? Owners only,
+  // as in Field. It only reads, so an owner session is enough; it needs no
+  // second factor. With sign-in off it answers 503 like the person routes,
+  // and the server log still carries the notice (server/index.js).
+  if (updates) {
+    const updateStatus = async (_req, res) => res.json({ ok: true, ...(await updates.status()) });
+    if (auth?.personAuth) {
+      app.get('/api/updates', auth.personAuth.requireSession, auth.personAuth.requireRole('owner'), updateStatus);
+    } else {
+      app.get('/api/updates', (_req, res) => res.status(503).json({
+        ok: false,
+        code: 'sign_in_not_configured',
+        error: 'Sign-in is not configured on this installation (FLOW_AUTH is unset).',
+      }));
+    }
+  }
+
+  app.use(createSignInRouter({
+    settings: auth?.settings ?? { mode: 'off' },
+    db: database?.db ?? null,
+    clerk: auth?.clerk ?? null,
+    personAuth: auth?.personAuth ?? null,
+    log,
+  }));
+
+  return app;
+}

package/server/auth/clerk.js

@@ -0,0 +1,139 @@
+import { Readable } from 'node:stream';
+import { normaliseEmail } from './people.js';
+
+// Everything Flow asks of Clerk goes through one small adapter, so tests pass
+// a fake with the same members and never need keys or the network:
+//
+//   authenticate(req)        the verified session on this request, or null
+//   getUser(clerkUserId)     the Clerk user (emails, external accounts)
+//   findUserIdByEmail(email) the Clerk user with this email, or null
+//   createUser({ email })    a Clerk account with no password, for an invitee
+//
+// The real one is loaded only when FLOW_AUTH=clerk.
+export async function loadClerkAdapter({ secretKey, publishableKey, proxyUrl, authorizedParties = [] }) {
+  const { createClerkClient } = await import('@clerk/backend');
+  // No SDK telemetry: Flow sends Clerk only what sign-in needs.
+  const client = createClerkClient({ secretKey, publishableKey, ...(proxyUrl ? { proxyUrl } : {}), telemetry: { disabled: true } });
+  return {
+    async authenticate(req) {
+      // Only the Authorization header is read. Flow never accepts the session
+      // cookie, so another site cannot make a browser act with it.
+      const headers = new Headers();
+      if (typeof req.headers.authorization === 'string') headers.set('authorization', req.headers.authorization);
+      const request = new Request(`${req.protocol}://${req.get('host')}${req.originalUrl}`, { method: req.method, headers });
+      const state = await client.authenticateRequest(request, {
+        acceptsToken: 'session_token',
+        ...(authorizedParties.length ? { authorizedParties } : {}),
+      });
+      return state.isAuthenticated ? state.toAuth() : null;
+    },
+    getUser: (clerkUserId) => client.users.getUser(clerkUserId),
+    async findUserIdByEmail(email) {
+      const { data } = await client.users.getUserList({ emailAddress: [email], limit: 1 });
+      return data[0]?.id ?? null;
+    },
+    async createUser({ email }) {
+      const user = await client.users.createUser({ emailAddress: [email], skipPasswordRequirement: true });
+      return user.id;
+    },
+  };
+}
+
+// An invitee needs a Clerk account before their first sign-in, because with
+// public sign-up off Flow's sign-in page never creates one. The account has
+// the invitee's email (verified, since the backend made it) and no password;
+// their first Google sign-in on that address joins it.
+export async function ensureClerkAccount(clerk, email) {
+  const existing = await clerk.findUserIdByEmail(email);
+  if (existing) return { clerkUserId: existing, created: false };
+  return { clerkUserId: await clerk.createUser({ email }), created: true };
+}
+
+// The Clerk user's primary email and whether Clerk has verified it. Flow
+// links people only by a verified primary address.
+export function primaryEmailOf(clerkUser) {
+  const addresses = Array.isArray(clerkUser?.emailAddresses) ? clerkUser.emailAddresses : [];
+  const primary = addresses.find((address) => address?.id === clerkUser?.primaryEmailAddressId) ?? null;
+  if (!primary) return { email: null, verified: false };
+  return { email: normaliseEmail(primary.emailAddress), verified: primary.verification?.status === 'verified' };
+}
+
+export function displayNameOf(clerkUser) {
+  const name = [clerkUser?.firstName, clerkUser?.lastName].map((part) => String(part || '').trim()).filter(Boolean).join(' ');
+  return name || null;
+}
+
+// Clerk's `fva` claim is [minutes since first factor, minutes since second
+// factor]; the second is -1 when the session never passed a second factor.
+export function secondFactorVerified(auth, maxAgeMinutes) {
+  const fva = Array.isArray(auth?.factorVerificationAge) ? auth.factorVerificationAge
+    : Array.isArray(auth?.sessionClaims?.fva) ? auth.sessionClaims.fva : null;
+  const age = fva?.[1];
+  return typeof age === 'number' && Number.isFinite(age) && age >= 0 && age <= maxAgeMinutes;
+}
+
+// The Google Workspace owner path. The Clerk user has a verified Google
+// account whose email is the owner's Flow email, on an allowed domain, and
+// no password, so Google (and the 2-Step Verification its Workspace
+// enforces) is the only way into that account.
+export function googleWorkspaceOwner(clerkUser, flowEmail, allowedDomains) {
+  if (!clerkUser || !allowedDomains?.length) return false;
+  if (clerkUser.passwordEnabled !== false) return false;
+  const email = normaliseEmail(flowEmail);
+  const domain = email.slice(email.lastIndexOf('@') + 1);
+  if (!email.includes('@') || !allowedDomains.includes(domain)) return false;
+  const accounts = Array.isArray(clerkUser.externalAccounts) ? clerkUser.externalAccounts : [];
+  return accounts.some((account) => ['oauth_google', 'google'].includes(String(account?.provider).toLowerCase())
+    && account?.verification?.status === 'verified'
+    && normaliseEmail(account?.emailAddress) === email);
+}
+
+// The path part of CLERK_PROXY_URL with no trailing slash, or null.
+export function resolveClerkProxyPath(proxyUrl) {
+  if (!proxyUrl) return null;
+  let pathname;
+  try {
+    pathname = new URL(proxyUrl, 'http://flow.invalid').pathname;
+  } catch {
+    throw new Error('CLERK_PROXY_URL is not a valid URL or path');
+  }
+  return pathname.replace(/\/+$/, '') || null;
+}
+
+// Replit's managed Clerk publishes the app with CLERK_PROXY_URL, so the
+// browser talks to Clerk's Frontend API through Flow's own origin. Clerk's
+// SDK does the forwarding; this turns Express's request into a web Request
+// and streams the answer back. Mount it before any body parser.
+export function createClerkProxy({ proxyPath, publishableKey, secretKey, proxy }) {
+  return async function clerkProxy(req, res, next) {
+    try {
+      const headers = new Headers();
+      for (const [name, value] of Object.entries(req.headers)) {
+        if (value === undefined) continue;
+        if (Array.isArray(value)) value.forEach((item) => headers.append(name, item));
+        else headers.set(name, value);
+      }
+      // The client address as Express resolved it, so a client cannot hand
+      // Clerk a forged X-Forwarded-For.
+      headers.delete('x-forwarded-for');
+      if (req.ip) headers.set('x-forwarded-for', req.ip);
+      const hasBody = req.method !== 'GET' && req.method !== 'HEAD';
+      const request = new Request(`${req.protocol}://${req.get('host')}${req.originalUrl}`, {
+        method: req.method,
+        headers,
+        ...(hasBody ? { body: Readable.toWeb(req), duplex: 'half' } : {}),
+      });
+      const response = await proxy(request, { proxyPath, publishableKey, secretKey });
+      res.status(response.status);
+      for (const [name, value] of response.headers) {
+        if (name !== 'set-cookie') res.setHeader(name, value);
+      }
+      const cookies = response.headers.getSetCookie?.() ?? [];
+      if (cookies.length) res.setHeader('set-cookie', cookies);
+      if (!response.body || req.method === 'HEAD') return res.end();
+      Readable.fromWeb(response.body).on('error', next).pipe(res);
+    } catch (error) {
+      next(error);
+    }
+  };
+}

package/server/auth/people.js

@@ -0,0 +1,138 @@
+import { and, asc, eq, isNull, ne, sql } from 'drizzle-orm';
+import { people, PERSON_ROLES } from '../db/schema.js';
+import { FlowError } from '../core/errors.js';
+import { isPlainEmail } from './settings.js';
+
+// The people who may sign in, and their roles. Only an owner changes this
+// table (server/auth/routes.js); sign-in only reads it and links a row to its
+// Clerk user on the first verified sign-in.
+
+export function normaliseEmail(email) {
+  return String(email ?? '').trim().toLowerCase();
+}
+
+export function publicPerson(row) {
+  return {
+    id: row.id,
+    email: row.email,
+    name: row.name,
+    role: row.role,
+    status: row.status,
+    // An invitation the person has not taken up yet.
+    invited: !row.clerkUserId,
+    createdAt: row.createdAt?.toISOString?.() ?? row.createdAt,
+  };
+}
+
+export async function findPersonById(db, id) {
+  const [row] = await db.select().from(people).where(eq(people.id, id));
+  return row ?? null;
+}
+
+export async function findPersonByClerkId(db, clerkUserId) {
+  const [row] = await db.select().from(people).where(eq(people.clerkUserId, clerkUserId));
+  return row ?? null;
+}
+
+export async function findPersonByEmail(db, email) {
+  const [row] = await db.select().from(people).where(eq(people.email, normaliseEmail(email)));
+  return row ?? null;
+}
+
+export function listPeople(db) {
+  return db.select().from(people).orderBy(asc(people.status), asc(people.email));
+}
+
+function checkRole(role) {
+  if (!PERSON_ROLES.includes(role)) throw new FlowError('invalid', `role must be one of ${PERSON_ROLES.join(', ')}`);
+}
+
+// An owner invites someone by email. They get in on their first sign-in with
+// a verified Clerk account on that address.
+export async function invitePerson(db, { email, name = null, role, invitedBy = null }) {
+  const address = normaliseEmail(email);
+  if (!isPlainEmail(address)) throw new FlowError('invalid', 'email must be a plain (ASCII) email address');
+  checkRole(role);
+  const [row] = await db.insert(people)
+    .values({ email: address, name: name?.trim() || null, role, status: 'active', invitedBy })
+    .onConflictDoNothing({ target: people.email })
+    .returning();
+  if (!row) throw new FlowError('conflict', 'that email address is already on the people list');
+  return row;
+}
+
+// Public sign-up only: someone Flow does not know, waiting for an owner.
+export async function recordPendingPerson(db, { email, name, clerkUserId }) {
+  const [row] = await db.insert(people)
+    .values({ email: normaliseEmail(email), name: name || null, role: 'staff', status: 'pending', clerkUserId, linkedAt: new Date() })
+    .onConflictDoNothing()
+    .returning();
+  return row ?? null;
+}
+
+// Links an invitation to the Clerk user who signed in with its verified
+// email. Only an unlinked row links, so a concurrent sign-in cannot take it.
+export async function linkPerson(db, { id, clerkUserId }) {
+  const [row] = await db.update(people)
+    .set({ clerkUserId, linkedAt: new Date(), updatedAt: new Date() })
+    .where(and(eq(people.id, id), isNull(people.clerkUserId)))
+    .returning();
+  return row ?? null;
+}
+
+// While the installation has no owner, invite `email` as its owner (or make
+// that person the owner if they are already listed). Returns the row, or null
+// when an owner already exists.
+export async function seedFirstOwner(db, email) {
+  return db.transaction(async (tx) => {
+    await tx.execute(sql`lock table ${people} in share row exclusive mode`);
+    const [owner] = await tx.select({ id: people.id }).from(people).where(eq(people.role, 'owner')).limit(1);
+    if (owner) return null;
+    const address = normaliseEmail(email);
+    const [row] = await tx.insert(people)
+      .values({ email: address, role: 'owner', status: 'active' })
+      .onConflictDoUpdate({ target: people.email, set: { role: 'owner', status: 'active', updatedAt: new Date() } })
+      .returning();
+    return row;
+  });
+}
+
+// Changes made by an owner. Flow always keeps one active owner, and an owner
+// never changes or removes themself (so nobody locks themself out by mistake).
+export async function updatePerson(db, { id, actorId, role, status }) {
+  if (role !== undefined) checkRole(role);
+  if (status !== undefined && !['active', 'disabled'].includes(status)) {
+    throw new FlowError('invalid', 'status must be active or disabled');
+  }
+  if (id === actorId) throw new FlowError('forbidden', 'you cannot change your own role or access');
+  return db.transaction(async (tx) => {
+    await tx.execute(sql`lock table ${people} in share row exclusive mode`);
+    const current = await findPersonById(tx, id);
+    if (!current) throw new FlowError('not_found', 'person not found');
+    const next = { role: role ?? current.role, status: status ?? current.status };
+    if (current.role === 'owner' && current.status === 'active' && (next.role !== 'owner' || next.status !== 'active')) {
+      await assertAnotherOwner(tx, id);
+    }
+    const [row] = await tx.update(people).set({ ...next, updatedAt: new Date() }).where(eq(people.id, id)).returning();
+    return row;
+  });
+}
+
+export async function removePerson(db, { id, actorId }) {
+  if (id === actorId) throw new FlowError('forbidden', 'you cannot remove yourself');
+  return db.transaction(async (tx) => {
+    await tx.execute(sql`lock table ${people} in share row exclusive mode`);
+    const current = await findPersonById(tx, id);
+    if (!current) throw new FlowError('not_found', 'person not found');
+    if (current.role === 'owner' && current.status === 'active') await assertAnotherOwner(tx, id);
+    await tx.delete(people).where(eq(people.id, id));
+    return current;
+  });
+}
+
+async function assertAnotherOwner(tx, id) {
+  const [other] = await tx.select({ id: people.id }).from(people)
+    .where(and(eq(people.role, 'owner'), eq(people.status, 'active'), ne(people.id, id)))
+    .limit(1);
+  if (!other) throw new FlowError('conflict', 'Flow needs at least one active owner');
+}

package/server/auth/routes.js

@@ -0,0 +1,143 @@
+import { fileURLToPath } from 'node:url';
+import express from 'express';
+import { FlowError } from '../core/errors.js';
+import { ensureClerkAccount } from './clerk.js';
+import {
+  findPersonByEmail,
+  invitePerson,
+  listPeople,
+  normaliseEmail,
+  publicPerson,
+  removePerson,
+  updatePerson,
+} from './people.js';
+import { isPlainEmail } from './settings.js';
+
+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
+// 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
+    ? proxyUrl.replace(/\/+$/, '')
+    : `https://${Buffer.from(publishableKey.split('_')[2] ?? '', 'base64').toString('utf8').replace(/\$$/, '')}`;
+  return `${base}/npm/@clerk/clerk-js@6/dist/clerk.browser.js`;
+}
+
+function sendError(res, error, log) {
+  if (error instanceof FlowError) {
+    return res.status(ERROR_STATUS[error.code] ?? 400).json({ ok: false, code: error.code, error: error.message });
+  }
+  log.error?.(`[people] ${error.message}`);
+  return res.status(500).json({ ok: false, code: 'internal', error: 'Something went wrong.' });
+}
+
+// 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 }) {
+  const router = express.Router();
+  const signInOn = settings.mode === 'clerk';
+
+  // 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) => {
+    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) },
+    });
+  });
+
+  router.get('/', (_req, res) => res.redirect(302, '/sign-in'));
+  router.get('/sign-in', (_req, res) => {
+    res.set('Cache-Control', 'no-store');
+    res.set('X-Frame-Options', 'DENY');
+    res.sendFile(signInPage);
+  });
+
+  if (!signInOn) {
+    router.use(['/api/me', '/api/people'], (_req, res) => res.status(503).json({
+      ok: false,
+      code: 'sign_in_not_configured',
+      error: 'Sign-in is not configured on this installation (FLOW_AUTH is unset).',
+    }));
+    return router;
+  }
+
+  const { requireSession, requireOwner, ownerVerification } = personAuth;
+
+  router.get('/api/me', requireSession, async (req, res) => {
+    const body = { ok: true, person: publicPerson(req.person) };
+    if (req.person.role === 'owner') {
+      const check = await ownerVerification(req.person, req.clerkAuth);
+      body.ownerActions = { allowed: Boolean(check.verified), by: check.by ?? null };
+    }
+    res.json(body);
+  });
+
+  // Only an owner manages people.
+  const people = express.Router();
+  people.use(requireSession, requireOwner, express.json({ limit: '16kb' }));
+  people.param('id', (_req, res, next, id) => (UUID.test(id) ? next() : res.status(404).json({ ok: false, code: 'not_found', error: 'person not found' })));
+
+  people.get('/', async (_req, res) => {
+    try {
+      res.json({ ok: true, people: (await listPeople(db)).map(publicPerson) });
+    } catch (error) {
+      sendError(res, error, log);
+    }
+  });
+
+  // Invite someone. Flow also makes sure they have a Clerk account, because
+  // with public sign-up off the sign-in page never creates one.
+  people.post('/', async (req, res) => {
+    try {
+      const email = normaliseEmail(req.body?.email);
+      const role = req.body?.role;
+      if (!isPlainEmail(email)) throw new FlowError('invalid', 'email must be a plain (ASCII) email address');
+      if (await findPersonByEmail(db, email)) throw new FlowError('conflict', 'that email address is already on the people list');
+      try {
+        await ensureClerkAccount(clerk, email);
+      } catch (error) {
+        log.error?.(`[people] Clerk account for an invitation failed: ${error.message}`);
+        return res.status(503).json({ ok: false, code: 'sign_in_unavailable', error: 'Flow could not prepare the sign-in account. Try again shortly.' });
+      }
+      const person = await invitePerson(db, { email, name: req.body?.name ?? null, role, invitedBy: req.person.id });
+      log.info?.(`[people] ${req.person.id} invited ${person.id} as ${person.role}`);
+      res.status(201).json({ ok: true, person: publicPerson(person) });
+    } catch (error) {
+      sendError(res, error, log);
+    }
+  });
+
+  people.patch('/:id', async (req, res) => {
+    try {
+      const person = await updatePerson(db, { id: req.params.id, actorId: req.person.id, role: req.body?.role, status: req.body?.status });
+      log.info?.(`[people] ${req.person.id} set ${person.id} to ${person.role}, ${person.status}`);
+      res.json({ ok: true, person: publicPerson(person) });
+    } catch (error) {
+      sendError(res, error, log);
+    }
+  });
+
+  people.delete('/:id', async (req, res) => {
+    try {
+      const person = await removePerson(db, { id: req.params.id, actorId: req.person.id });
+      log.info?.(`[people] ${req.person.id} removed ${person.id}`);
+      res.json({ ok: true });
+    } catch (error) {
+      sendError(res, error, log);
+    }
+  });
+
+  router.use('/api/people', people);
+  return router;
+}