@arcforgelabs/flow 2026.10.21 → 2026.10.23

package/server/core/links.js

@@ -0,0 +1,166 @@
+import { and, eq, sql } from 'drizzle-orm';
+import { externalLinks, LINK_ENTITIES, LINK_MATCHES, priorLinks } from '../db/schema.js';
+import { FlowError, notFound } from './errors.js';
+import { openReview, resolveReviewFor } from './review.js';
+
+// The identity map (issue 57). It records that a Flow record and a record in
+// another system are the same thing, how Flow knows, and who confirmed it.
+// Pushes, imports and the ledger read the link first; matching by name only
+// ever proposes one.
+//
+// A link is exact when Flow made the external record, or both sides carry the
+// same id. A name match is a guess: it stays `proposed` and opens a review item
+// until a person confirms it. A link is never deleted; a replaced one is
+// `superseded`.
+
+const EXACT = new Set(['created_by_flow', 'exact_id', 'imported', 'person']);
+
+function check({ entity, flowId, system, externalId, matchedBy }) {
+  if (!LINK_ENTITIES.includes(entity)) throw new FlowError('invalid', `unknown link entity: ${entity}`);
+  if (!LINK_MATCHES.includes(matchedBy)) throw new FlowError('invalid', `unknown match: ${matchedBy}`);
+  if (!flowId || !system || !externalId) throw new FlowError('invalid', 'flowId, system and externalId are required');
+}
+
+// Two callers that link the same external record, or the same Flow record, at
+// the same time take turns: the decision below reads, then writes.
+async function lockPair(tx, organisationId, { system, entity, externalId, flowId }) {
+  const keys = [
+    `link:${organisationId}:${system}:${entity}:ext:${externalId}`,
+    `link:${organisationId}:${system}:${entity}:flow:${flowId}`,
+  ].sort();
+  for (const key of keys) await tx.execute(sql`select pg_advisory_xact_lock(hashtextextended(${key}, 0))`);
+}
+
+async function activeBy(tx, organisationId, { system, entity }, column, value) {
+  const [row] = await tx.select().from(externalLinks).where(and(
+    eq(externalLinks.organisationId, organisationId),
+    eq(externalLinks.system, system),
+    eq(externalLinks.entity, entity),
+    eq(column, value),
+    eq(externalLinks.state, 'active'),
+  ));
+  return row ?? null;
+}
+
+// Records a link. Answers `{ outcome, link }`:
+// - `linked`: a new active link;
+// - `existing`: the same active link was already there;
+// - `proposed`: a guess, waiting for a person (a review item is open);
+// - `conflict`: one side already links elsewhere. Nothing changes; a review
+//   item holds both sides.
+export async function linkRecord(db, organisationId, link) {
+  check(link);
+  const { entity, flowId, system, externalId, matchedBy } = link;
+  return db.transaction(async (tx) => {
+    await lockPair(tx, organisationId, link);
+    const byExternal = await activeBy(tx, organisationId, link, externalLinks.externalId, externalId);
+    if (byExternal?.flowId === flowId) return { outcome: 'existing', link: byExternal };
+    const byFlow = await activeBy(tx, organisationId, link, externalLinks.flowId, flowId);
+    if (byExternal || byFlow) {
+      await openReview(tx, organisationId, {
+        kind: 'link.conflict',
+        entity,
+        flowId,
+        systems: [system],
+        evidence: {
+          proposed: { system, externalId, matchedBy },
+          linkedExternal: byExternal && { flowId: byExternal.flowId, externalId: byExternal.externalId },
+          linkedFlow: byFlow && { flowId: byFlow.flowId, externalId: byFlow.externalId },
+        },
+      });
+      return { outcome: 'conflict', link: byExternal ?? byFlow };
+    }
+    const state = EXACT.has(matchedBy) ? 'active' : 'proposed';
+    const [waiting] = await tx.select().from(externalLinks).where(and(
+      eq(externalLinks.organisationId, organisationId),
+      eq(externalLinks.system, system),
+      eq(externalLinks.entity, entity),
+      eq(externalLinks.externalId, externalId),
+      eq(externalLinks.flowId, flowId),
+      eq(externalLinks.state, 'proposed'),
+    ));
+    if (waiting && state === 'proposed') return { outcome: 'proposed', link: waiting };
+    if (waiting) {
+      // Exact evidence for a pair a person was asked about settles the question.
+      await tx.update(externalLinks).set({ state: 'superseded', updatedAt: sql`now()` })
+        .where(eq(externalLinks.id, waiting.id));
+      await resolveReviewFor(tx, organisationId, {
+        kind: 'link.proposed', entity, flowId, resolution: `exact:${matchedBy}`, actor: 'system:links',
+      });
+    }
+    const [row] = await tx.insert(externalLinks)
+      .values({ organisationId, entity, flowId, system, externalId, matchedBy, state })
+      .returning();
+    if (state === 'proposed') {
+      await openReview(tx, organisationId, {
+        kind: 'link.proposed',
+        entity,
+        flowId,
+        systems: [system],
+        evidence: { linkId: row.id, system, externalId, matchedBy },
+      });
+    }
+    return { outcome: state === 'active' ? 'linked' : 'proposed', link: row };
+  });
+}
+
+// A person confirms a proposed link. It becomes active, unless either side
+// gained an active link meanwhile.
+export async function confirmLink(db, organisationId, linkId, { personId = null, actor }) {
+  if (!actor) throw new FlowError('invalid', 'actor is required');
+  return db.transaction(async (tx) => {
+    const [proposed] = await tx.select().from(externalLinks)
+      .where(and(eq(externalLinks.organisationId, organisationId), eq(externalLinks.id, linkId)));
+    if (!proposed) throw notFound('link');
+    await lockPair(tx, organisationId, proposed);
+    const [current] = await tx.select().from(externalLinks)
+      .where(eq(externalLinks.id, linkId)).for('update');
+    if (current.state !== 'proposed') throw new FlowError('conflict', 'link is not waiting for a person', { state: current.state });
+    const taken = await activeBy(tx, organisationId, current, externalLinks.externalId, current.externalId)
+      ?? await activeBy(tx, organisationId, current, externalLinks.flowId, current.flowId);
+    if (taken) throw new FlowError('conflict', 'one side already has an active link', { linkId: taken.id });
+    const [row] = await tx.update(externalLinks)
+      .set({ state: 'active', confirmedBy: personId, confirmedAt: sql`now()`, updatedAt: sql`now()` })
+      .where(eq(externalLinks.id, linkId))
+      .returning();
+    await resolveReviewFor(tx, organisationId, {
+      kind: 'link.proposed', entity: row.entity, flowId: row.flowId, resolution: 'confirmed', actor,
+    });
+    return row;
+  });
+}
+
+// Ends a link (for example when the external record was merged or deleted).
+export async function supersedeLink(db, organisationId, linkId) {
+  const [row] = await db.update(externalLinks)
+    .set({ state: 'superseded', updatedAt: sql`now()` })
+    .where(and(eq(externalLinks.organisationId, organisationId), eq(externalLinks.id, linkId)))
+    .returning();
+  if (!row) throw notFound('link');
+  return row;
+}
+
+// The Flow record an external record is, through an active link, or null.
+export async function flowIdFor(db, organisationId, { system, entity, externalId }) {
+  const row = await activeBy(db, organisationId, { system, entity }, externalLinks.externalId, externalId);
+  return row?.flowId ?? null;
+}
+
+// The external id of a Flow record in one system, through an active link, or null.
+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/outbox.js

@@ -0,0 +1,129 @@
+import { and, eq, sql } from 'drizzle-orm';
+import { outbox } from '../db/schema.js';
+import { FlowError, notFound } from './errors.js';
+import { linkRecord } from './links.js';
+import { openReview } from './review.js';
+
+// The outbox. Every write Flow makes to another system is a row here first,
+// written in the same transaction as the Flow change it reports, with its
+// idempotency key. An adapter sends it through its governor and records what
+// came back. So a write is never lost, never made twice, and never made
+// without a record of why.
+//
+//   pending -> sending -> sent
+//                      -> ambiguous (outcome unknown: settle by a lookup first)
+//                      -> pending again (a retry) or failed (opens a review item)
+//   pending or ambiguous -> cancelled (a person)
+
+// How long a send may take before Flow treats its outcome as unknown.
+export const SEND_LEASE_MS = 10 * 60 * 1000;
+
+// Queues a write. Pass the transaction that makes the Flow change. A repeat with
+// the same key returns the first row; the same key for another record refuses.
+export async function queueWrite(tx, organisationId, {
+  system, action, entity, flowId, idempotencyKey, request, actor,
+}) {
+  if (!system || !action || !entity || !flowId) throw new FlowError('invalid', 'system, action, entity and flowId are required');
+  if (!idempotencyKey) throw new FlowError('invalid', 'idempotencyKey is required');
+  if (!actor) throw new FlowError('invalid', 'actor is required');
+  const [row] = await tx.insert(outbox)
+    .values({ organisationId, system, action, entity, flowId, idempotencyKey, request, createdBy: actor })
+    .onConflictDoNothing({ target: outbox.idempotencyKey })
+    .returning();
+  if (row) return { write: row, queued: true };
+  const [first] = await tx.select().from(outbox).where(eq(outbox.idempotencyKey, idempotencyKey));
+  if (first.organisationId !== organisationId || first.flowId !== flowId || first.action !== action) {
+    throw new FlowError('conflict', 'idempotency key already used for another write');
+  }
+  return { write: first, queued: false };
+}
+
+// Claims pending writes for one system. A write left `sending` past the lease
+// (the process died mid-call) becomes `ambiguous`: the call may have left.
+export async function claimWrites(db, { system, limit = 10, leaseMs = SEND_LEASE_MS }) {
+  return db.transaction(async (tx) => {
+    await tx.update(outbox)
+      .set({ state: 'ambiguous', lastError: 'send did not finish', updatedAt: sql`now()` })
+      .where(and(
+        eq(outbox.system, system),
+        eq(outbox.state, 'sending'),
+        sql`${outbox.updatedAt} < now() - make_interval(secs => ${leaseMs / 1000})`,
+      ));
+    const { rows } = await tx.execute(sql`
+      select id from outbox where system = ${system} and state = 'pending'
+      order by created_at for update skip locked limit ${limit}`);
+    const claimed = [];
+    for (const { id } of rows) {
+      const [write] = await tx.update(outbox)
+        .set({ state: 'sending', attempts: sql`${outbox.attempts} + 1`, updatedAt: sql`now()` })
+        .where(eq(outbox.id, id))
+        .returning();
+      claimed.push(write);
+    }
+    return claimed;
+  });
+}
+
+// Moves one write from the states in `from` to new fields. Refuses a move from
+// any other state, so two workers can never both settle one write.
+async function move(tx, organisationId, writeId, from, fields) {
+  const [row] = await tx.update(outbox)
+    .set({ ...fields, updatedAt: sql`now()` })
+    .where(and(
+      eq(outbox.organisationId, organisationId),
+      eq(outbox.id, writeId),
+      sql`${outbox.state} in (${sql.join(from.map((s) => sql`${s}`), sql`, `)})`,
+    ))
+    .returning();
+  if (row) return row;
+  const [existing] = await tx.select().from(outbox)
+    .where(and(eq(outbox.organisationId, organisationId), eq(outbox.id, writeId)));
+  if (!existing) throw notFound('write');
+  throw new FlowError('conflict', `write is ${existing.state}`, { state: existing.state });
+}
+
+// The system made the record. Flow links its own record to it in the same
+// transaction, so the identity map always knows what Flow created.
+export async function markSent(db, organisationId, writeId, { externalId }) {
+  if (!externalId) throw new FlowError('invalid', 'externalId is required');
+  return db.transaction(async (tx) => {
+    const row = await move(tx, organisationId, writeId, ['sending', 'ambiguous'], {
+      state: 'sent', externalId, sentAt: sql`now()`, lastError: null,
+    });
+    const link = await linkRecord(tx, organisationId, {
+      entity: row.entity, flowId: row.flowId, system: row.system, externalId, matchedBy: 'created_by_flow',
+    });
+    return { write: row, link };
+  });
+}
+
+// The outcome is unknown (a timeout, a 5xx after the request left). The adapter
+// must look in the system before it sends again.
+export async function markAmbiguous(db, organisationId, writeId, { error }) {
+  return move(db, organisationId, writeId, ['sending'], { state: 'ambiguous', lastError: String(error).slice(0, 2000) });
+}
+
+// The system refused the write, or a lookup found it was never made. With
+// `retry` it goes back to pending; without, it fails and opens a review item.
+export async function markFailed(db, organisationId, writeId, { error, retry = false }) {
+  const message = String(error).slice(0, 2000);
+  if (retry) return move(db, organisationId, writeId, ['sending', 'ambiguous'], { state: 'pending', lastError: message });
+  return db.transaction(async (tx) => {
+    const row = await move(tx, organisationId, writeId, ['sending', 'ambiguous'], { state: 'failed', lastError: message });
+    await openReview(tx, organisationId, {
+      kind: 'write.failed',
+      entity: row.entity,
+      flowId: row.flowId,
+      systems: [row.system],
+      evidence: { writeId: row.id, action: row.action, attempts: row.attempts, error: message },
+    });
+    return row;
+  });
+}
+
+export async function cancelWrite(db, organisationId, writeId, { actor }) {
+  if (!actor) throw new FlowError('invalid', 'actor is required');
+  return move(db, organisationId, writeId, ['pending', 'ambiguous', 'failed'], {
+    state: 'cancelled', lastError: `cancelled by ${actor}`,
+  });
+}

package/server/core/queue.js

@@ -0,0 +1,142 @@
+import { and, eq, sql } from 'drizzle-orm';
+import { backgroundJobs } from '../db/schema.js';
+import { FlowError } from './errors.js';
+import { openReview } from './review.js';
+
+// The background job queue (issue 6). Every sync and write step runs as a job
+// here, so steps never overlap, a crash never loses one, and a person can see
+// what is queued, running or stuck. It is PostgreSQL only: workers claim with
+// FOR UPDATE SKIP LOCKED and hold a lease. A lease that runs out makes the job
+// claimable again, so a dead process never holds a job for good.
+
+export const DEFAULT_LEASE_MS = 5 * 60 * 1000;
+const FIRST_RETRY_MS = 60 * 1000;
+const LAST_RETRY_MS = 6 * 60 * 60 * 1000;
+
+// The wait before attempt `attempts + 1`: 1 minute, doubling, at most 6 hours.
+export function retryDelayMs(attempts) {
+  return Math.min(FIRST_RETRY_MS * 2 ** Math.max(0, attempts - 1), LAST_RETRY_MS);
+}
+
+// Queues a job. While a job with the same kind and dedupe key is queued or
+// running, it is returned instead of a second one.
+export async function enqueueJob(db, organisationId, {
+  kind, dedupeKey = '', payload = {}, runAfter = null, maxAttempts = 8,
+}) {
+  if (!kind) throw new FlowError('invalid', 'kind is required');
+  const [row] = await db.insert(backgroundJobs)
+    .values({ organisationId, kind, dedupeKey, payload, maxAttempts, ...(runAfter ? { runAfter } : {}) })
+    .onConflictDoNothing()
+    .returning();
+  if (row) return { job: row, queued: true };
+  const [open] = await db.select().from(backgroundJobs).where(and(
+    eq(backgroundJobs.organisationId, organisationId),
+    eq(backgroundJobs.kind, kind),
+    eq(backgroundJobs.dedupeKey, dedupeKey),
+    sql`${backgroundJobs.state} in ('queued', 'running')`,
+  ));
+  return { job: open, queued: false };
+}
+
+async function giveUp(tx, job, error) {
+  const [row] = await tx.update(backgroundJobs)
+    .set({ state: 'dead', lockedBy: null, lockedUntil: null, lastError: error, updatedAt: sql`now()` })
+    .where(eq(backgroundJobs.id, job.id))
+    .returning();
+  await openReview(tx, job.organisationId, {
+    kind: 'job.dead',
+    entity: 'background_job',
+    flowId: job.id,
+    evidence: { kind: job.kind, dedupeKey: job.dedupeKey, attempts: job.attempts, error },
+  });
+  return row;
+}
+
+// Claims up to `limit` due jobs for one worker. A running job whose lease ran
+// out is due again; one that has used every attempt is given up instead.
+export async function claimJobs(db, { workerId, kinds = null, limit = 1, leaseMs = DEFAULT_LEASE_MS }) {
+  if (!workerId) throw new FlowError('invalid', 'workerId is required');
+  return db.transaction(async (tx) => {
+    const kindFilter = kinds?.length
+      ? sql`and kind in (${sql.join(kinds.map((k) => sql`${k}`), sql`, `)})`
+      : sql``;
+    const { rows: due } = await tx.execute(sql`
+      select id, attempts, max_attempts from background_jobs
+      where ((state = 'queued' and run_after <= now()) or (state = 'running' and locked_until < now()))
+      ${kindFilter}
+      order by run_after, created_at
+      for update skip locked
+      limit ${limit}`);
+    const claimed = [];
+    for (const candidate of due) {
+      if (candidate.attempts >= candidate.max_attempts) {
+        const [job] = await tx.select().from(backgroundJobs).where(eq(backgroundJobs.id, candidate.id));
+        await giveUp(tx, job, job.lastError ?? 'lease ran out on the last attempt');
+        continue;
+      }
+      const [job] = await tx.update(backgroundJobs)
+        .set({
+          state: 'running',
+          lockedBy: workerId,
+          lockedUntil: sql`now() + make_interval(secs => ${leaseMs / 1000})`,
+          attempts: sql`${backgroundJobs.attempts} + 1`,
+          updatedAt: sql`now()`,
+        })
+        .where(eq(backgroundJobs.id, candidate.id))
+        .returning();
+      claimed.push(job);
+    }
+    return claimed;
+  });
+}
+
+// Only the worker that holds the lease may finish a job. A worker whose lease
+// ran out and was taken over finishes nothing and is told so.
+async function finish(db, job, workerId, fields) {
+  const [row] = await db.update(backgroundJobs)
+    .set({ ...fields, lockedBy: null, lockedUntil: null, updatedAt: sql`now()` })
+    .where(and(
+      eq(backgroundJobs.id, job.id),
+      eq(backgroundJobs.state, 'running'),
+      eq(backgroundJobs.lockedBy, workerId),
+      eq(backgroundJobs.attempts, job.attempts),
+    ))
+    .returning();
+  if (!row) throw new FlowError('conflict', 'job lease was lost', { jobId: job.id });
+  return row;
+}
+
+export async function completeJob(db, job, { workerId, result = null }) {
+  return finish(db, job, workerId, { state: 'succeeded', result, lastError: null });
+}
+
+// A failed attempt waits and runs again, until its attempts run out or the
+// error cannot be fixed by waiting (`retry: false`); then it opens a review item.
+export async function failJob(db, job, { workerId, error, retry = true }) {
+  const message = String(error?.message ?? error ?? 'failed').slice(0, 2000);
+  if (!retry || job.attempts >= job.maxAttempts) {
+    return db.transaction(async (tx) => {
+      const row = await finish(tx, job, workerId, { state: 'running', lastError: message });
+      return giveUp(tx, { ...row, attempts: job.attempts }, message);
+    });
+  }
+  return finish(db, job, workerId, {
+    state: 'queued',
+    lastError: message,
+    runAfter: sql`now() + make_interval(secs => ${retryDelayMs(job.attempts) / 1000})`,
+  });
+}
+
+// Claims one due job and runs its handler. Answers what happened, or null when
+// nothing was due. A handler throws to fail; `error.retry = false` gives up.
+export async function runNextJob(db, { workerId, handlers, leaseMs }) {
+  const [job] = await claimJobs(db, { workerId, kinds: Object.keys(handlers), limit: 1, leaseMs });
+  if (!job) return null;
+  try {
+    const result = await handlers[job.kind](job);
+    return { job: await completeJob(db, job, { workerId, result: result ?? null }), outcome: 'succeeded' };
+  } catch (error) {
+    const row = await failJob(db, job, { workerId, error, retry: error?.retry !== false });
+    return { job: row, outcome: row.state };
+  }
+}

package/server/core/review.js

@@ -0,0 +1,92 @@
+import { and, asc, desc, eq, sql } from 'drizzle-orm';
+import { reviewItems } from '../db/schema.js';
+import { FlowError, notFound } from './errors.js';
+
+// The review queue (issue 59). Everything a person must decide is one row
+// here: a link Flow could not prove, a write that failed for good, a job that
+// gave up, a difference between two systems. Flow never settles a conflict by
+// overwriting one side; it opens an item and waits for a person.
+
+function requireActor(actor) {
+  if (!actor) throw new FlowError('invalid', 'actor is required');
+}
+
+// Opens an item, or updates the one open item for the same kind and record:
+// a repeat finding refreshes the evidence and never makes a second item.
+export async function openReview(db, organisationId, {
+  kind, entity, flowId, systems = [], evidence = {}, moneyAtRiskCents = 0,
+}) {
+  if (!kind || !entity || !flowId) throw new FlowError('invalid', 'kind, entity and flowId are required');
+  if (!Number.isSafeInteger(moneyAtRiskCents) || moneyAtRiskCents < 0) {
+    throw new FlowError('invalid', 'moneyAtRiskCents must be whole, non-negative cents');
+  }
+  const [row] = await db.insert(reviewItems)
+    .values({ organisationId, kind, entity, flowId, systems, evidence, moneyAtRiskCents })
+    .onConflictDoUpdate({
+      target: [reviewItems.organisationId, reviewItems.kind, reviewItems.entity, reviewItems.flowId],
+      targetWhere: sql`state = 'open'`,
+      set: {
+        systems,
+        evidence,
+        moneyAtRiskCents,
+        seenCount: sql`${reviewItems.seenCount} + 1`,
+        updatedAt: sql`now()`,
+      },
+    })
+    .returning();
+  return row;
+}
+
+// Closes an open item with the choice a person made. `dismiss` records that
+// nothing needed doing.
+export async function resolveReview(db, organisationId, reviewId, { resolution, note = null, actor, dismiss = false }) {
+  requireActor(actor);
+  if (!resolution) throw new FlowError('invalid', 'resolution is required');
+  const [row] = await db.update(reviewItems)
+    .set({
+      state: dismiss ? 'dismissed' : 'resolved',
+      resolution,
+      note,
+      resolvedBy: actor,
+      resolvedAt: sql`now()`,
+      updatedAt: sql`now()`,
+    })
+    .where(and(
+      eq(reviewItems.organisationId, organisationId),
+      eq(reviewItems.id, reviewId),
+      eq(reviewItems.state, 'open'),
+    ))
+    .returning();
+  if (row) return row;
+  const [existing] = await db.select().from(reviewItems)
+    .where(and(eq(reviewItems.organisationId, organisationId), eq(reviewItems.id, reviewId)));
+  if (!existing) throw notFound('review item');
+  throw new FlowError('conflict', 'review item is already closed', { state: existing.state });
+}
+
+// Closes the open item for one record and kind, when the cause went away on its
+// own (for example a person confirmed a link from another screen).
+export async function resolveReviewFor(db, organisationId, { kind, entity, flowId, resolution, actor }) {
+  requireActor(actor);
+  const rows = await db.update(reviewItems)
+    .set({ state: 'resolved', resolution, resolvedBy: actor, resolvedAt: sql`now()`, updatedAt: sql`now()` })
+    .where(and(
+      eq(reviewItems.organisationId, organisationId),
+      eq(reviewItems.kind, kind),
+      eq(reviewItems.entity, entity),
+      eq(reviewItems.flowId, flowId),
+      eq(reviewItems.state, 'open'),
+    ))
+    .returning();
+  return rows[0] ?? null;
+}
+
+// The queue a person works through: most money at risk first, then oldest.
+export async function listReview(db, organisationId, { state = 'open', kind, limit = 100 } = {}) {
+  const filters = [eq(reviewItems.organisationId, organisationId), eq(reviewItems.state, state)];
+  if (kind) filters.push(eq(reviewItems.kind, kind));
+  return db.select().from(reviewItems)
+    .where(and(...filters))
+    .orderBy(desc(reviewItems.moneyAtRiskCents), asc(reviewItems.createdAt))
+    .limit(limit);
+}

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');
+  }
+}