@arcforgelabs/flow 2026.10.18 → 2026.10.19

package/server/integrations/xero/runtime.js

@@ -0,0 +1,135 @@
+import { createXeroClient, xeroError } from './client.js';
+import { decryptToken, readConnection, storeRotatedToken } from './connections.js';
+import { createGovernor } from './governor.js';
+import { createStateStore, refreshTokens } from './oauth.js';
+import { createReplayFetch, DEFAULT_REPLAY_FIXTURES, loadReplayFixtures } from './replay.js';
+import { resolveXeroSettings, writesAllowed } from './settings.js';
+
+// The Xero adapter's state for one Flow process: settings, the rate-limit
+// governor, the transport (real fetch, or replay), OAuth states, and the
+// access tokens in memory. Access tokens live 30 minutes and are never
+// stored; the refresh token is stored sealed (connections.js).
+
+export function requireXeroSettings(env = process.env) {
+  const settings = resolveXeroSettings(env);
+  if (!settings) {
+    throw new Error('FLOW_INTEGRATIONS turns Xero on, so XERO_MODE must be "live", "sandbox" or "replay" (docs/XERO.md)');
+  }
+  return settings;
+}
+
+export function createXeroRuntime({ settings, fetch, now = Date.now, log = console } = {}) {
+  if (!settings) throw new TypeError('createXeroRuntime: settings are required');
+  const transport = fetch
+    ?? (settings.mode === 'replay' ? createReplayFetch(loadReplayFixtures(settings.replayFixtures ?? DEFAULT_REPLAY_FIXTURES)) : globalThis.fetch);
+  const governor = createGovernor({
+    config: { dayLimit: settings.dayLimit, usageWarningFraction: settings.usageWarningFraction },
+    now,
+    log,
+  });
+  const states = createStateStore({ now });
+  const accessTokens = new Map(); // organisation id -> { token, expiresAt }
+  const refreshing = new Map(); // organisation id -> promise
+  const queues = new Map(); // organisation id -> tail of its work queue
+
+  // Runs heavy Xero work for one organisation one at a time, in order: a
+  // sync and a batch of drafts draw on the same call budget, and running them
+  // together only buys 429s.
+  function serial(organisationId, fn) {
+    const run = (queues.get(organisationId) ?? Promise.resolve()).then(fn);
+    const tail = run.catch(() => {});
+    queues.set(organisationId, tail);
+    tail.then(() => {
+      if (queues.get(organisationId) === tail) queues.delete(organisationId);
+    });
+    return run;
+  }
+
+  function remember(organisationId, tokens) {
+    const seconds = Number(tokens.expires_in) || 1800;
+    accessTokens.set(organisationId, { token: tokens.access_token, expiresAt: now() + Math.max(5, seconds - 60) * 1000 });
+  }
+
+  // A stored connection made in another mode is not used: a sandbox
+  // connection never serves live, and the other way round.
+  function usable(connection) {
+    if (!connection) {
+      throw xeroError('xero_not_connected', 'Xero is not connected. An owner must connect Xero first.', { status: 409 });
+    }
+    if (connection.mode !== settings.mode) {
+      throw xeroError('xero_mode_changed', `Xero was connected in ${connection.mode} mode, and XERO_MODE is now ${settings.mode}. An owner must connect Xero again.`, { status: 409 });
+    }
+    if (settings.tenantId && connection.tenantId !== settings.tenantId) {
+      throw xeroError('xero_wrong_organisation', 'The connected Xero organisation is not the one XERO_TENANT_ID names. An owner must connect Xero again.', { status: 409 });
+    }
+    return connection;
+  }
+
+  // Refresh under a row lock, and store the rotated refresh token in the same
+  // transaction, so two refreshes never race and the newest token is kept.
+  async function refresh(db, organisationId) {
+    return db.transaction(async (tx) => {
+      const connection = usable(await readConnection(tx, organisationId, { lock: true }));
+      const refreshToken = decryptToken(connection.refreshTokenEnc, settings.tokenKey, organisationId);
+      const tokens = await refreshTokens(settings, transport, refreshToken);
+      await storeRotatedToken(tx, organisationId, { refreshToken: tokens.refresh_token, scope: tokens.scope, key: settings.tokenKey });
+      remember(organisationId, tokens);
+      return tokens.access_token;
+    });
+  }
+
+  async function accessToken(db, organisationId) {
+    const cached = accessTokens.get(organisationId);
+    if (cached && cached.expiresAt > now()) return cached.token;
+    if (!refreshing.has(organisationId)) {
+      refreshing.set(organisationId, refresh(db, organisationId).finally(() => refreshing.delete(organisationId)));
+    }
+    return refreshing.get(organisationId);
+  }
+
+  // A client for one Flow organisation's connected Xero.
+  async function clientFor(db, organisationId) {
+    const connection = usable(await readConnection(db, organisationId));
+    const client = createXeroClient({
+      tenantId: connection.tenantId,
+      accessToken: () => accessToken(db, organisationId),
+      invalidateAccessToken: () => accessTokens.delete(organisationId),
+      fetch: transport,
+      governor,
+      apiBase: settings.endpoints.api,
+      log,
+    });
+    return { client, connection };
+  }
+
+  // A sandbox acts only on a Xero Demo Company: Flow proves it before it
+  // connects and before every write, and fails closed if it cannot.
+  async function assertEnvironment(client) {
+    if (settings.mode !== 'sandbox') return;
+    const organisation = await client.getOrganisation();
+    if (organisation?.Class !== 'DEMO') {
+      throw xeroError('xero_not_demo', 'XERO_MODE=sandbox acts only on a Xero Demo Company, and this organisation is not one.', { status: 409 });
+    }
+  }
+
+  function assertWritesAllowed() {
+    if (!writesAllowed(settings)) {
+      throw xeroError('xero_writes_off', 'XERO_MODE=live writes to Xero only when XERO_ALLOW_LIVE_WRITES=on.', { status: 409 });
+    }
+  }
+
+  return {
+    settings,
+    transport,
+    governor,
+    states,
+    remember,
+    forget: (organisationId) => accessTokens.delete(organisationId),
+    clientFor,
+    serial,
+    assertEnvironment,
+    assertWritesAllowed,
+    log,
+    now,
+  };
+}

package/server/integrations/xero/settings.js

@@ -0,0 +1,170 @@
+// Xero adapter settings, read from the environment once at boot. Errors name
+// the variable, never its value: XERO_CLIENT_SECRET and XERO_TOKEN_KEY must
+// never reach a log.
+//
+// XERO_MODE turns the adapter on and says which Xero it acts on (issue #10).
+// It has no default: unset, the adapter is off.
+//   live     the lab's own Xero organisation. Draft invoices are written only
+//            when XERO_ALLOW_LIVE_WRITES=on as well.
+//   sandbox  a Xero Demo Company. Flow refuses any organisation whose class
+//            is not DEMO, so a sandbox can never write to a real ledger.
+//   replay   no network: recorded, synthetic Xero responses
+//            (server/integrations/xero/fixtures). Development and CI.
+
+export const XERO_MODES = Object.freeze(['live', 'sandbox', 'replay']);
+
+// Xero's own public endpoints. They are the same for every installation.
+export const XERO_ENDPOINTS = Object.freeze({
+  api: 'https://api.xero.com/api.xro/2.0',
+  authorize: 'https://login.xero.com/identity/connect/authorize',
+  token: 'https://identity.xero.com/connect/token',
+  revoke: 'https://identity.xero.com/connect/revocation',
+  connections: 'https://api.xero.com/connections',
+  // Deep links into the Xero web app, for a person to open a record.
+  web: 'https://go.xero.com',
+});
+
+export const XERO_CALLBACK_PATH = '/api/xero/oauth/callback';
+export const DEFAULT_XERO_SCOPE = 'offline_access accounting.contacts accounting.invoices accounting.settings.read';
+export const DEFAULT_XERO_DAY_LIMIT = 1000;
+export const DEFAULT_DUE_DAYS = 30;
+
+function readEnv(env, name) {
+  const value = env?.[name];
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function readOnOff(env, name) {
+  const raw = readEnv(env, name).toLowerCase();
+  if (raw === '' || raw === 'off') return false;
+  if (raw === 'on') return true;
+  throw new Error(`${name} must be "on", "off" or unset`);
+}
+
+function readPositiveInteger(env, name, fallback) {
+  const raw = readEnv(env, name);
+  if (!raw) return fallback;
+  const value = Number(raw);
+  if (!Number.isSafeInteger(value) || value <= 0) throw new Error(`${name} must be a positive whole number`);
+  return value;
+}
+
+function readFraction(env, name, fallback) {
+  const raw = readEnv(env, name);
+  if (!raw) return fallback;
+  const value = Number(raw);
+  if (!Number.isFinite(value) || value <= 0 || value > 1) throw new Error(`${name} must be a number above 0 and at most 1`);
+  return value;
+}
+
+// A 32-byte key as 64 hex characters or base64. Returns null, never the input.
+export function decodeTokenKey(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;
+}
+
+// The callback address Xero sends the owner back to. XERO_REDIRECT_URI wins;
+// otherwise it is this installation's FLOW_PUBLIC_ORIGIN plus the callback
+// path. It must match a redirect URI registered on the Xero app exactly.
+export function resolveRedirectUri(env = process.env) {
+  const explicit = readEnv(env, 'XERO_REDIRECT_URI');
+  const origin = readEnv(env, 'FLOW_PUBLIC_ORIGIN');
+  const raw = explicit || (origin ? `${origin.replace(/\/+$/, '')}${XERO_CALLBACK_PATH}` : '');
+  if (!raw) return null;
+  const name = explicit ? 'XERO_REDIRECT_URI' : 'FLOW_PUBLIC_ORIGIN';
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new Error(`${name} must be an absolute URL`);
+  }
+  const local = url.hostname === 'localhost' || url.hostname === '127.0.0.1';
+  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && local)) {
+    throw new Error(`${name} must be https (Xero accepts http only for localhost)`);
+  }
+  if (url.pathname !== XERO_CALLBACK_PATH || url.search || url.hash) {
+    throw new Error(`XERO_REDIRECT_URI must end in ${XERO_CALLBACK_PATH}, with no query`);
+  }
+  return url.toString();
+}
+
+function resolveTaxTypes(env) {
+  return {
+    GST: readEnv(env, 'XERO_TAX_TYPE_GST') || 'OUTPUT',
+    GST_FREE: readEnv(env, 'XERO_TAX_TYPE_GST_FREE') || 'EXEMPTOUTPUT',
+  };
+}
+
+function resolveTracking(env) {
+  const category = readEnv(env, 'XERO_TRACKING_CATEGORY');
+  const option = readEnv(env, 'XERO_TRACKING_OPTION');
+  if (!category && !option) return null;
+  if (!category || !option) throw new Error('XERO_TRACKING_CATEGORY and XERO_TRACKING_OPTION are set together');
+  return { category, option };
+}
+
+// null when the adapter is off. Otherwise the settings the adapter needs.
+export function resolveXeroSettings(env = process.env) {
+  const mode = readEnv(env, 'XERO_MODE').toLowerCase();
+  if (!mode) return null;
+  if (!XERO_MODES.includes(mode)) throw new Error('XERO_MODE must be "live", "sandbox", "replay" or unset');
+
+  const clientId = readEnv(env, 'XERO_CLIENT_ID');
+  const clientSecret = readEnv(env, 'XERO_CLIENT_SECRET');
+  const tokenKey = decodeTokenKey(readEnv(env, 'XERO_TOKEN_KEY'));
+  if (mode !== 'replay') {
+    const missing = [];
+    if (!clientId) missing.push('XERO_CLIENT_ID');
+    if (!clientSecret) missing.push('XERO_CLIENT_SECRET');
+    if (missing.length) throw new Error(`XERO_MODE=${mode} needs ${missing.join(' and ')} (from the Xero app)`);
+  }
+  if (readEnv(env, 'XERO_TOKEN_KEY') && !tokenKey) {
+    throw new Error('XERO_TOKEN_KEY must be a 32-byte key, as 64 hex characters or base64');
+  }
+  if (mode !== 'replay' && !tokenKey) {
+    throw new Error(`XERO_MODE=${mode} needs XERO_TOKEN_KEY (a 32-byte key that encrypts the Xero refresh token)`);
+  }
+
+  const tenantId = readEnv(env, 'XERO_TENANT_ID') || null;
+  const tenantName = readEnv(env, 'XERO_TENANT_NAME') || null;
+  // A live connection must name the organisation it is for, so an owner who
+  // can see several Xero organisations cannot connect the wrong one.
+  if (mode === 'live' && !tenantId && !tenantName) {
+    throw new Error('XERO_MODE=live needs XERO_TENANT_ID or XERO_TENANT_NAME (the lab\'s Xero organisation)');
+  }
+
+  const invoiceNumber = (readEnv(env, 'XERO_INVOICE_NUMBER') || 'xero').toLowerCase();
+  if (!['xero', 'flow'].includes(invoiceNumber)) throw new Error('XERO_INVOICE_NUMBER must be "xero", "flow" or unset');
+
+  return {
+    mode,
+    clientId: clientId || (mode === 'replay' ? 'replay-client-id' : ''),
+    clientSecret: clientSecret || (mode === 'replay' ? 'replay-client-secret' : ''),
+    tokenKey,
+    redirectUri: resolveRedirectUri(env),
+    scope: readEnv(env, 'XERO_SCOPE') || DEFAULT_XERO_SCOPE,
+    tenantId,
+    tenantName,
+    liveWrites: readOnOff(env, 'XERO_ALLOW_LIVE_WRITES'),
+    dayLimit: readPositiveInteger(env, 'XERO_DAY_LIMIT', DEFAULT_XERO_DAY_LIMIT),
+    usageWarningFraction: readFraction(env, 'XERO_USAGE_WARNING_FRACTION', 0.7),
+    taxTypes: resolveTaxTypes(env),
+    tracking: resolveTracking(env),
+    defaultDueDays: readPositiveInteger(env, 'XERO_DEFAULT_DUE_DAYS', DEFAULT_DUE_DAYS),
+    invoiceNumber,
+    replayFixtures: readEnv(env, 'XERO_REPLAY_FIXTURES') || null,
+    endpoints: XERO_ENDPOINTS,
+  };
+}
+
+// Whether this installation may write to Xero now. Reads always may.
+export function writesAllowed(settings) {
+  if (!settings) return false;
+  return settings.mode !== 'live' || settings.liveWrites === true;
+}

package/server/rate-limit.js

@@ -1,21 +1,15 @@
+import expressRateLimit from 'express-rate-limit';
+
 // 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.' });
-  };
+// Express's `trust proxy`). In memory: one Flow process serves one lab. Each
+// call makes its own counter. Built on express-rate-limit, which CodeQL
+// recognises as rate limiting (js/missing-rate-limiting).
+export function rateLimit({ limit, windowMs }) {
+  return expressRateLimit({
+    limit,
+    windowMs,
+    standardHeaders: 'draft-8', // RateLimit-Policy, RateLimit and Retry-After
+    legacyHeaders: false,
+    handler: (_req, res) => res.status(429).json({ ok: false, code: 'rate_limited', error: 'Too many requests. Wait and try again.' }),
+  });
 }