@arcforgelabs/flow 2026.10.22 → 2026.10.24

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.10.22",
+  "version": "2026.10.24",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@arcforgelabs/flow",
-      "version": "2026.10.22",
+      "version": "2026.10.24",
       "license": "MIT",
       "dependencies": {
         "@clerk/backend": "3.23.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcforgelabs/flow",
-  "version": "2026.10.22",
+  "version": "2026.10.24",
   "description": "Invoicing, bill entry and a financial dashboard for labs, with Seazona and Xero integrations.",
   "license": "MIT",
   "repository": {

package/server/app.js

@@ -3,6 +3,7 @@ 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 { createSetupRouter } from './integrations/setup.js';
 import { rateLimit } from './rate-limit.js';
 import { DEFAULT_FAMILY } from './theme/themes.js';
 import { messagePage } from './ui/page.js';
@@ -30,6 +31,7 @@ export function createApp({
   auth = null,
   updates = null,
   integrations = null,
+  secrets = null,
   trustProxy = false,
   rateLimitPerMinute = 120,
   signInRateLimitPerMinute = 30,
@@ -93,6 +95,11 @@ export function createApp({
   // An adapter's own pages (such as the end of connecting Xero) use
   // `messagePage` so they look like the rest of Flow.
   const page = (options) => messagePage({ ...options, defaultFamily });
+  // Settings, Integrations: an owner turns integrations on and enters their
+  // settings (server/integrations/setup.js).
+  if (integrations && database && auth?.personAuth) {
+    app.use('/api/integrations', createSetupRouter({ db: database.db, registry: integrations, personAuth: auth.personAuth, secrets, log }));
+  }
   for (const { path, handler } of integrations?.routes({ db: database?.db ?? null, personAuth: auth?.personAuth ?? null, log, messagePage: page }) ?? []) {
     app.use(path, handler);
   }

package/server/core/links.js

@@ -1,5 +1,5 @@
 import { and, eq, sql } from 'drizzle-orm';
-import { externalLinks, LINK_ENTITIES, LINK_MATCHES } from '../db/schema.js';
+import { externalLinks, LINK_ENTITIES, LINK_MATCHES, priorLinks } from '../db/schema.js';
 import { FlowError, notFound } from './errors.js';
 import { openReview, resolveReviewFor } from './review.js';
 
@@ -151,3 +151,16 @@ export async function externalIdFor(db, organisationId, { system, entity, flowId
   const row = await activeBy(db, organisationId, { system, entity }, externalLinks.flowId, flowId);
   return row?.externalId ?? null;
 }
+
+// The link an earlier installation held for a work system's job, if any
+// (`prior_links`). The pipeline reads it when the job first becomes an
+// obligation (#58).
+export async function priorLinkFor(db, organisationId, { sourceSystem, sourceJobRef, system }) {
+  const [row] = await db.select().from(priorLinks).where(and(
+    eq(priorLinks.organisationId, organisationId),
+    eq(priorLinks.sourceSystem, sourceSystem),
+    eq(priorLinks.sourceJobRef, sourceJobRef),
+    eq(priorLinks.system, system),
+  ));
+  return row ?? null;
+}

package/server/core/secrets.js

@@ -0,0 +1,74 @@
+import { createCipheriv, createDecipheriv, createHash, hkdfSync, randomBytes } from 'node:crypto';
+import { FlowError } from './errors.js';
+
+// Flow's one secrets key. It encrypts the integration credentials an owner
+// enters in Settings (server/integrations/setup.js) before they reach
+// PostgreSQL, and derives each integration's own token key. It never sits in
+// the database, so a copy of the database alone reads no credential.
+//
+// FLOW_SECRETS_KEY is the key: 32 bytes, as 64 hex characters or base64.
+// When it is unset, Flow derives the key from SESSION_SECRET, a long random
+// secret many hosts already hold. Changing the source makes stored
+// credentials unreadable: an owner enters them again.
+
+const MIN_SESSION_SECRET = 32;
+
+export function decodeKey(raw) {
+  const value = String(raw ?? '').trim();
+  if (!value) return null;
+  if (/^[0-9a-f]{64}$/i.test(value)) return Buffer.from(value, 'hex');
+  if (/^[A-Za-z0-9+/]{43}=?$/.test(value)) {
+    const key = Buffer.from(value, 'base64');
+    if (key.length === 32) return key;
+  }
+  return null;
+}
+
+const keyId = (key) => createHash('sha256').update(key).digest('hex').slice(0, 12);
+
+// Answers { key, id, source } or null when neither setting gives a key. A
+// FLOW_SECRETS_KEY that is not a key stops boot, so a typo never falls back.
+export function resolveSecretsKey(env = process.env) {
+  const raw = String(env.FLOW_SECRETS_KEY ?? '').trim();
+  if (raw) {
+    const key = decodeKey(raw);
+    if (!key) throw new Error('FLOW_SECRETS_KEY must be a 32-byte key, as 64 hex characters or base64');
+    return { key, id: keyId(key), source: 'FLOW_SECRETS_KEY' };
+  }
+  const session = String(env.SESSION_SECRET ?? '').trim();
+  if (session.length >= MIN_SESSION_SECRET) {
+    const key = Buffer.from(hkdfSync('sha256', session, 'flow', 'flow-secrets-key-v1', 32));
+    return { key, id: keyId(key), source: 'SESSION_SECRET' };
+  }
+  return null;
+}
+
+// A separate key for one purpose (for example `XERO_TOKEN_KEY`), so no two
+// uses share a key.
+export function deriveKey(secrets, purpose) {
+  return Buffer.from(hkdfSync('sha256', secrets.key, 'flow', `flow-derived-${purpose}`, 32));
+}
+
+// AES-256-GCM. `context` (the integration and the setting's name) is bound
+// as associated data, so a value moved to another setting does not open.
+export function sealSecret(secrets, plaintext, context) {
+  const iv = randomBytes(12);
+  const cipher = createCipheriv('aes-256-gcm', secrets.key, iv);
+  cipher.setAAD(Buffer.from(context));
+  const data = Buffer.concat([cipher.update(String(plaintext), 'utf8'), cipher.final()]);
+  return { v: 1, key: secrets.id, iv: iv.toString('base64'), tag: cipher.getAuthTag().toString('base64'), data: data.toString('base64') };
+}
+
+export function openSecret(secrets, sealed, context) {
+  if (!secrets || !sealed || sealed.v !== 1 || sealed.key !== secrets.id) {
+    throw new FlowError('secret_unreadable', 'this credential was stored with another key; enter it again');
+  }
+  try {
+    const decipher = createDecipheriv('aes-256-gcm', secrets.key, Buffer.from(sealed.iv, 'base64'));
+    decipher.setAAD(Buffer.from(context));
+    decipher.setAuthTag(Buffer.from(sealed.tag, 'base64'));
+    return Buffer.concat([decipher.update(Buffer.from(sealed.data, 'base64')), decipher.final()]).toString('utf8');
+  } catch {
+    throw new FlowError('secret_unreadable', 'this credential cannot be read; enter it again');
+  }
+}

package/server/db/migrations/0006_prior_links.sql

@@ -0,0 +1,18 @@
+CREATE TABLE "prior_links" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"organisation_id" uuid NOT NULL,
+	"source_system" text NOT NULL,
+	"source_job_ref" text NOT NULL,
+	"system" text NOT NULL,
+	"external_id" text NOT NULL,
+	"external_number" text,
+	"matched_by" text NOT NULL,
+	"matched_at" timestamp with time zone,
+	"origin" text NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "prior_links_matched_by_valid" CHECK (matched_by in ('person', 'imported'))
+);
+--> statement-breakpoint
+ALTER TABLE "prior_links" ADD CONSTRAINT "prior_links_organisation_id_organisations_id_fk" FOREIGN KEY ("organisation_id") REFERENCES "public"."organisations"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+CREATE UNIQUE INDEX "prior_links_job" ON "prior_links" USING btree ("organisation_id","source_system","source_job_ref","system");--> statement-breakpoint
+CREATE INDEX "prior_links_external" ON "prior_links" USING btree ("organisation_id","system","external_id");

package/server/db/migrations/0007_integration_settings.sql

@@ -0,0 +1,23 @@
+CREATE TABLE "integration_setting_events" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"adapter_id" text NOT NULL,
+	"kind" text NOT NULL,
+	"settings" text[] DEFAULT '{}'::text[] NOT NULL,
+	"actor" uuid,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "integration_setting_events_kind_valid" CHECK (kind in ('turned_on', 'turned_off', 'setting_changed', 'secret_set', 'secret_removed'))
+);
+--> statement-breakpoint
+CREATE TABLE "integration_settings" (
+	"adapter_id" text PRIMARY KEY NOT NULL,
+	"enabled" boolean DEFAULT false NOT NULL,
+	"config" jsonb DEFAULT '{}'::jsonb NOT NULL,
+	"secrets" jsonb DEFAULT '{}'::jsonb NOT NULL,
+	"updated_by" uuid,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "integration_setting_events" ADD CONSTRAINT "integration_setting_events_actor_people_id_fk" FOREIGN KEY ("actor") REFERENCES "public"."people"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "integration_settings" ADD CONSTRAINT "integration_settings_updated_by_people_id_fk" FOREIGN KEY ("updated_by") REFERENCES "public"."people"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "integration_setting_events_adapter" ON "integration_setting_events" USING btree ("adapter_id","created_at");