@arcforgelabs/flow 0.0.0-stage → 2026.10.18

package/server/auth/session.js

@@ -0,0 +1,170 @@
+import { displayNameOf, googleWorkspaceOwner, primaryEmailOf, secondFactorVerified } from './clerk.js';
+import { findPersonByClerkId, findPersonByEmail, linkPerson, recordPendingPerson } from './people.js';
+import { DEFAULT_OWNER_MFA_MAX_AGE_MINUTES, isPlainEmail } from './settings.js';
+
+// Checks the Clerk session on every person request, then maps the Clerk user
+// to a Flow person by verified email. Clerk proves who someone is; the
+// `people` table decides whether they get in and what they may do. A Clerk
+// account with no Flow person gets no access.
+
+const DENIALS = {
+  signed_out: [401, 'Sign in to Flow.'],
+  session_expired: [401, 'Your sign-in has expired. Sign in again.'],
+  email_unverified: [403, 'Flow links your sign-in by your verified email address. Verify your primary email, then sign in again.'],
+  email_not_plain: [403, 'Flow only accepts plain (ASCII) email addresses.'],
+  email_linked_elsewhere: [403, 'That email address is already linked to a different sign-in. Ask a Flow owner.'],
+  not_invited: [403, 'This installation is invitation only. Ask a Flow owner to invite you.'],
+  access_pending: [403, "You're signed in, but a Flow owner still needs to approve your access."],
+  access_disabled: [403, 'Your Flow access has been turned off. Ask a Flow owner if this is a mistake.'],
+  role_required: [403, 'Your Flow role does not allow this.'],
+  owner_required: [403, 'Only a Flow owner can do this.'],
+  owner_verification_required: [403, null],
+  sign_in_unavailable: [503, 'Sign-in is unavailable right now. Try again shortly.'],
+};
+
+export function deny(res, code, error) {
+  const [status, message] = DENIALS[code] ?? DENIALS.signed_out;
+  return res.status(status).json({ ok: false, code, error: error ?? message });
+}
+
+function bearerToken(req) {
+  const header = req.headers.authorization;
+  if (typeof header !== 'string' || !header.startsWith('Bearer ')) return null;
+  return header.slice('Bearer '.length).trim() || null;
+}
+
+export function ownerVerificationMessage({ ownerGoogleDomains, ownerMfaMaxAgeMinutes }) {
+  const ways = [];
+  if (ownerGoogleDomains.length) {
+    ways.push(`sign in with Google using your work account (${ownerGoogleDomains.map((domain) => `@${domain}`).join(' or ')}), with no password set on your sign-in`);
+  }
+  ways.push(`sign in with a second factor (it counts for ${ownerMfaMaxAgeMinutes} minutes)`);
+  return `Owner actions need a verified owner sign-in. Sign out, then ${ways.join(', or ')}.`;
+}
+
+export function createPersonAuth({
+  db,
+  clerk,
+  publicSignUp = false,
+  ownerGoogleDomains = [],
+  ownerMfaMaxAgeMinutes = DEFAULT_OWNER_MFA_MAX_AGE_MINUTES,
+  log = console,
+  now = Date.now,
+  clerkUserCacheMs = 60 * 1000,
+}) {
+  if (!db) throw new Error('createPersonAuth: db is required');
+  if (!clerk?.authenticate || !clerk?.getUser) throw new Error('createPersonAuth: a Clerk adapter is required');
+  const ownerMessage = ownerVerificationMessage({ ownerGoogleDomains, ownerMfaMaxAgeMinutes });
+  // Clerk users fetched for the owner check, cached briefly so a burst of
+  // owner requests costs one Clerk call. Failures are never cached.
+  const clerkUsers = new Map();
+
+  // { person } or { denial }.
+  async function personFor(clerkUserId) {
+    const linked = await findPersonByClerkId(db, clerkUserId);
+    if (linked) return { person: linked };
+
+    const clerkUser = await clerk.getUser(clerkUserId);
+    const { email, verified } = primaryEmailOf(clerkUser);
+    if (!email || !verified) return { denial: 'email_unverified' };
+    if (!isPlainEmail(email)) return { denial: 'email_not_plain' };
+
+    const invited = await findPersonByEmail(db, email);
+    if (invited) {
+      if (invited.clerkUserId) return { denial: 'email_linked_elsewhere' };
+      const person = await linkPerson(db, { id: invited.id, clerkUserId });
+      if (person) {
+        log.info?.(`[auth] linked Clerk user ${clerkUserId} to Flow person ${person.id} (${person.role})`);
+        return { person };
+      }
+      const again = await findPersonByClerkId(db, clerkUserId);
+      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) {
+      log.warn?.(`[auth] Clerk user ${clerkUserId} refused: not invited`);
+      return { denial: 'not_invited' };
+    }
+    const person = await recordPendingPerson(db, { email, name: displayNameOf(clerkUser), clerkUserId });
+    if (!person) return { denial: 'access_pending' };
+    log.info?.(`[auth] Clerk user ${clerkUserId} asked for access; pending Flow person ${person.id}`);
+    return { person };
+  }
+
+  // Every person route starts here. The session token must be in the
+  // Authorization header; Clerk verifies it, and Flow checks its expiry too.
+  async function requireSession(req, res, next) {
+    if (!bearerToken(req)) return deny(res, 'signed_out');
+    let auth;
+    try {
+      auth = await clerk.authenticate(req);
+    } catch (error) {
+      log.error?.(`[auth] Clerk session check failed: ${error.message}`);
+      return deny(res, 'sign_in_unavailable');
+    }
+    if (!auth?.userId) return deny(res, 'signed_out');
+    const exp = auth.sessionClaims?.exp;
+    if (typeof exp === 'number' && exp * 1000 <= now()) return deny(res, 'session_expired');
+
+    let resolved;
+    try {
+      resolved = await personFor(auth.userId);
+    } catch (error) {
+      log.error?.(`[auth] Flow person lookup failed: ${error.message}`);
+      return deny(res, 'sign_in_unavailable');
+    }
+    if (resolved.denial) return deny(res, resolved.denial);
+    if (resolved.person.status === 'pending') return deny(res, 'access_pending');
+    if (resolved.person.status !== 'active') return deny(res, 'access_disabled');
+    req.person = resolved.person;
+    req.clerkAuth = auth;
+    return next();
+  }
+
+  function requireRole(...roles) {
+    return (req, res, next) => (roles.includes(req.person?.role) ? next() : deny(res, 'role_required'));
+  }
+
+  async function cachedClerkUser(clerkUserId) {
+    const cached = clerkUsers.get(clerkUserId);
+    if (cached && cached.expiresAt > now()) return cached.user;
+    const user = await clerk.getUser(clerkUserId);
+    if (clerkUsers.size > 100) clerkUsers.clear();
+    clerkUsers.set(clerkUserId, { user, expiresAt: now() + clerkUserCacheMs });
+    return user;
+  }
+
+  // Is this owner's sign-in strong enough for owner actions?
+  //   (a) the session passed a second factor within ownerMfaMaxAgeMinutes
+  //       (an installation with its own Clerk application and MFA on), or
+  //   (b) Google Workspace sign-in on an allowed domain with no password
+  //       (Replit's managed Clerk, which has no MFA).
+  // A Clerk error fails closed. Returns { verified, by } or { unavailable }.
+  async function ownerVerification(person, auth) {
+    if (secondFactorVerified(auth, ownerMfaMaxAgeMinutes)) return { verified: true, by: 'second_factor' };
+    if (!ownerGoogleDomains.length) return { verified: false, by: null };
+    try {
+      const clerkUser = await cachedClerkUser(auth.userId);
+      return googleWorkspaceOwner(clerkUser, person.email, ownerGoogleDomains)
+        ? { verified: true, by: 'google_workspace' }
+        : { verified: false, by: null };
+    } catch (error) {
+      log.error?.(`[auth] owner sign-in check failed: ${error.message}`);
+      return { unavailable: true };
+    }
+  }
+
+  // Owner-only routes: managing people, and later settings. Use after
+  // requireSession.
+  async function requireOwner(req, res, next) {
+    if (req.person?.role !== 'owner') return deny(res, 'owner_required');
+    const check = await ownerVerification(req.person, req.clerkAuth);
+    if (check.unavailable) return deny(res, 'sign_in_unavailable');
+    if (!check.verified) return deny(res, 'owner_verification_required', ownerMessage);
+    return next();
+  }
+
+  return { requireSession, requireRole, requireOwner, ownerVerification };
+}

package/server/auth/settings.js

@@ -0,0 +1,124 @@
+// Sign-in settings, read from the environment once at boot. Errors name the
+// variable, never its value: CLERK_SECRET_KEY must never reach a log.
+
+export const DEFAULT_OWNER_MFA_MAX_AGE_MINUTES = 12 * 60;
+
+function readEnv(env, name) {
+  const value = env?.[name];
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+// FLOW_AUTH: "clerk" signs people in with Clerk. Unset: sign-in is off and
+// every person route answers 503, so Flow never runs open. Any other value
+// stops boot, so a typo cannot quietly turn sign-in off.
+export function resolveAuthMode(env = process.env) {
+  const raw = readEnv(env, 'FLOW_AUTH').toLowerCase();
+  if (raw === '') return 'off';
+  if (raw === 'clerk') return 'clerk';
+  throw new Error('FLOW_AUTH must be "clerk" or unset');
+}
+
+// Replit's Clerk integration sets CLERK_SECRET_KEY and CLERK_PUBLISHABLE_KEY
+// (some templates name the second VITE_CLERK_PUBLISHABLE_KEY; either works).
+// CLERK_PROXY_URL is set on a published Replit app.
+export function resolveClerkKeys(env = process.env) {
+  const secretKey = readEnv(env, 'CLERK_SECRET_KEY');
+  const publishableSource = readEnv(env, 'CLERK_PUBLISHABLE_KEY') ? 'CLERK_PUBLISHABLE_KEY'
+    : readEnv(env, 'VITE_CLERK_PUBLISHABLE_KEY') ? 'VITE_CLERK_PUBLISHABLE_KEY' : null;
+  const publishableKey = publishableSource ? readEnv(env, publishableSource) : '';
+  const missing = [];
+  if (!secretKey) missing.push('CLERK_SECRET_KEY');
+  if (!publishableKey) missing.push('CLERK_PUBLISHABLE_KEY');
+  if (missing.length) {
+    throw new Error(`FLOW_AUTH=clerk needs ${missing.join(' and ')} (Replit: Tools > Users & Auth sets them)`);
+  }
+  if (!/^sk_(test|live)_\S+$/.test(secretKey)) {
+    throw new Error('CLERK_SECRET_KEY is not a Clerk secret key (expected sk_test_... or sk_live_...)');
+  }
+  if (!/^pk_(test|live)_\S+$/.test(publishableKey)) {
+    throw new Error(`${publishableSource} is not a Clerk publishable key (expected pk_test_... or pk_live_...)`);
+  }
+  return { secretKey, publishableKey, publishableSource, proxyUrl: readEnv(env, 'CLERK_PROXY_URL') || null };
+}
+
+// FLOW_PUBLIC_SIGN_UP: "on" lets anyone with a verified email ask for access
+// (they wait as `pending` until an owner approves them). Unset or "off": only
+// people an owner invited get in, and Flow's sign-in page creates no account.
+export function resolvePublicSignUp(env = process.env) {
+  const raw = readEnv(env, 'FLOW_PUBLIC_SIGN_UP').toLowerCase();
+  if (raw === '' || raw === 'off') return false;
+  if (raw === 'on') return true;
+  throw new Error('FLOW_PUBLIC_SIGN_UP must be "on", "off" or unset');
+}
+
+// FLOW_OWNER_MFA_MAX_AGE: how long a Clerk second factor counts for owner
+// actions. Minutes, or with an m/h suffix ("90m", "12h"). Default 12h.
+export function parseOwnerMfaMaxAge(raw) {
+  const value = String(raw ?? '').trim().toLowerCase();
+  if (!value) return DEFAULT_OWNER_MFA_MAX_AGE_MINUTES;
+  const match = /^(\d+)\s*(m|h)?$/.exec(value);
+  const minutes = match ? Number(match[1]) * (match[2] === 'h' ? 60 : 1) : NaN;
+  if (!Number.isSafeInteger(minutes) || minutes <= 0) {
+    throw new Error('FLOW_OWNER_MFA_MAX_AGE must be a positive number of minutes, or hours with "h" (e.g. 12h)');
+  }
+  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) {
+  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)');
+    }
+  }
+  return [...new Set(domains)];
+}
+
+// FLOW_PUBLIC_ORIGIN: the published app's origin. Clerk then accepts only
+// session tokens minted for it. Unset: Clerk's default.
+export function resolveAuthorizedParties(env = process.env) {
+  const raw = readEnv(env, 'FLOW_PUBLIC_ORIGIN');
+  if (!raw) return [];
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new Error('FLOW_PUBLIC_ORIGIN must be an absolute URL (e.g. https://flow.example.com)');
+  }
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+    throw new Error('FLOW_PUBLIC_ORIGIN must be an http(s) URL');
+  }
+  return [url.origin];
+}
+
+// FLOW_FIRST_OWNER_EMAIL: while the installation has no owner, Flow invites
+// this address as its owner at boot. Ignored once an owner exists.
+export function resolveFirstOwnerEmail(env = process.env) {
+  const email = readEnv(env, 'FLOW_FIRST_OWNER_EMAIL').toLowerCase();
+  if (!email) return null;
+  if (!isPlainEmail(email)) throw new Error('FLOW_FIRST_OWNER_EMAIL must be a plain (ASCII) email address');
+  return email;
+}
+
+// Flow emails are plain ASCII, so a look-alike character cannot pose as
+// someone else's address.
+export function isPlainEmail(email) {
+  return typeof email === 'string' && /^[\x21-\x3f\x41-\x7e]+@[a-z0-9.-]+\.[a-z0-9-]+$/i.test(email);
+}
+
+export function resolveSignInSettings(env = process.env) {
+  const mode = resolveAuthMode(env);
+  if (mode === 'off') return { mode };
+  return {
+    mode,
+    keys: resolveClerkKeys(env),
+    publicSignUp: resolvePublicSignUp(env),
+    ownerMfaMaxAgeMinutes: parseOwnerMfaMaxAge(readEnv(env, 'FLOW_OWNER_MFA_MAX_AGE')),
+    ownerGoogleDomains: parseOwnerGoogleDomains(readEnv(env, 'FLOW_OWNER_GOOGLE_DOMAINS')),
+    authorizedParties: resolveAuthorizedParties(env),
+    firstOwnerEmail: resolveFirstOwnerEmail(env),
+  };
+}

package/server/auth/sign-in.html

@@ -0,0 +1,184 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="referrer" content="no-referrer">
+<title>Sign in to Flow</title>
+<style>
+  :root { color-scheme: light dark; --fg: #1d1d1f; --bg: #f7f7f8; --muted: #66666e; --line: #d9d9de; --accent: #2f5bd3; }
+  @media (prefers-color-scheme: dark) { :root { --fg: #ececf0; --bg: #16161a; --muted: #a0a0aa; --line: #34343c; --accent: #7d9cf0; } }
+  body { margin: 0; font: 16px/1.5 system-ui, sans-serif; color: var(--fg); background: var(--bg); }
+  main { max-width: 760px; margin: 0 auto; padding: 32px 16px; }
+  h1 { font-size: 1.4rem; margin: 0 0 16px; }
+  h2 { font-size: 1.1rem; margin: 32px 0 8px; }
+  p.note { color: var(--muted); }
+  .error { color: #c62828; }
+  table { width: 100%; border-collapse: collapse; }
+  th, td { text-align: left; padding: 6px 4px; border-bottom: 1px solid var(--line); vertical-align: middle; }
+  form { display: flex; flex-wrap: wrap; gap: 8px; margin-top: 8px; }
+  input, select, button { font: inherit; padding: 6px 8px; }
+  button { cursor: pointer; }
+  [hidden] { display: none !important; }
+</style>
+</head>
+<body>
+<main>
+  <h1>Flow</h1>
+  <p id="status" class="note">Loading sign-in…</p>
+  <div id="sign-in"></div>
+  <section id="signed-in" hidden>
+    <p>Signed in as <strong id="me-email"></strong> (<span id="me-role"></span>). <button id="sign-out" type="button">Sign out</button></p>
+    <p id="owner-note" class="note" hidden></p>
+    <section id="people-section" hidden>
+      <h2>People</h2>
+      <table>
+        <thead><tr><th>Email</th><th>Role</th><th>Access</th><th></th></tr></thead>
+        <tbody id="people"></tbody>
+      </table>
+      <h2>Invite someone</h2>
+      <form id="invite">
+        <input name="email" type="email" required placeholder="name@example.com" autocomplete="off">
+        <select name="role"><option value="staff">staff</option><option value="admin">admin</option><option value="owner">owner</option></select>
+        <button type="submit">Invite</button>
+      </form>
+      <p id="people-error" class="error" role="alert"></p>
+    </section>
+  </section>
+</main>
+<script type="module">
+// Flow's sign-in page. Clerk's sign-in widget signs people in; Flow then
+// decides what they may do (GET /api/me). Every Flow request carries the
+// session token in the Authorization header. Text from the server is only
+// ever set with textContent.
+const $ = (id) => document.getElementById(id);
+const status = (text, isError = false) => { $('status').textContent = text; $('status').className = isError ? 'error' : 'note'; };
+
+const config = await fetch('/api/auth/config').then((res) => res.json()).catch(() => null);
+if (!config || config.mode !== 'clerk') {
+  status('Sign-in is not configured on this installation. The operator sets FLOW_AUTH=clerk (docs/SELF_HOSTING.md).', true);
+} else {
+  await loadClerk(config.clerk);
+  const Clerk = window.Clerk;
+  await Clerk.load();
+  Clerk.addListener(({ user }) => { if (user && $('signed-in').hidden) showSignedIn(); });
+  if (Clerk.user) {
+    await showSignedIn();
+  } else {
+    status(config.publicSignUp ? 'Sign in, or ask for access.' : 'Sign in with the account you were invited with.');
+    // With public sign-up off the widget never creates a Clerk account: no
+    // sign-up link, and an OAuth sign-in for an unknown email is not turned
+    // into a sign-up (transferable: false).
+    Clerk.mountSignIn($('sign-in'), {
+      forceRedirectUrl: '/sign-in',
+      withSignUp: config.publicSignUp,
+      transferable: config.publicSignUp,
+      ...(config.publicSignUp ? {} : { appearance: { elements: { footerAction: { display: 'none' } } } }),
+    });
+  }
+}
+
+function loadClerk({ publishableKey, proxyUrl, scriptUrl }) {
+  return new Promise((resolve, reject) => {
+    const script = document.createElement('script');
+    script.src = scriptUrl;
+    script.crossOrigin = 'anonymous';
+    script.dataset.clerkPublishableKey = publishableKey;
+    if (proxyUrl) script.dataset.clerkProxyUrl = proxyUrl;
+    script.onload = resolve;
+    script.onerror = () => { status('Could not load sign-in. Try again shortly.', true); reject(new Error('clerk-js')); };
+    document.head.append(script);
+  });
+}
+
+async function flow(path, options = {}) {
+  const token = await window.Clerk.session?.getToken();
+  const res = await fetch(path, {
+    ...options,
+    headers: { Authorization: `Bearer ${token}`, ...(options.body ? { 'Content-Type': 'application/json' } : {}) },
+  });
+  const body = await res.json().catch(() => ({ ok: false, error: `HTTP ${res.status}` }));
+  if (!res.ok) throw new Error(body.error || `HTTP ${res.status}`);
+  return body;
+}
+
+async function showSignedIn() {
+  $('sign-in').replaceChildren();
+  $('sign-out').onclick = () => window.Clerk.signOut({ redirectUrl: '/sign-in' });
+  let me;
+  try {
+    me = await flow('/api/me');
+  } catch (error) {
+    status(error.message, true);
+    $('signed-in').hidden = false;
+    $('me-email').textContent = window.Clerk.user?.primaryEmailAddress?.emailAddress ?? '';
+    $('me-role').textContent = 'no Flow access';
+    return;
+  }
+  status('');
+  $('signed-in').hidden = false;
+  $('me-email').textContent = me.person.email;
+  $('me-role').textContent = me.person.role;
+  if (me.person.role !== 'owner') return;
+  if (!me.ownerActions?.allowed) {
+    $('owner-note').hidden = false;
+    $('owner-note').textContent = 'Managing people needs a verified owner sign-in: Google Workspace on the owner domain with no password, or a second factor.';
+    return;
+  }
+  $('people-section').hidden = false;
+  $('invite').onsubmit = async (event) => {
+    event.preventDefault();
+    const form = new FormData(event.target);
+    await act(() => flow('/api/people', { method: 'POST', body: JSON.stringify({ email: form.get('email'), role: form.get('role') }) }));
+    event.target.reset();
+  };
+  await renderPeople(me.person.id);
+}
+
+async function act(fn) {
+  $('people-error').textContent = '';
+  try {
+    await fn();
+  } catch (error) {
+    $('people-error').textContent = error.message;
+  }
+  const me = await flow('/api/me');
+  await renderPeople(me.person.id);
+}
+
+async function renderPeople(selfId) {
+  const { people } = await flow('/api/people');
+  const rows = people.map((person) => {
+    const tr = document.createElement('tr');
+    const email = document.createElement('td');
+    email.textContent = person.email + (person.invited ? ' (invited)' : '');
+    const role = document.createElement('td');
+    const access = document.createElement('td');
+    const actions = document.createElement('td');
+    if (person.id === selfId) {
+      role.textContent = person.role;
+      access.textContent = person.status;
+    } else {
+      const select = document.createElement('select');
+      for (const value of ['owner', 'admin', 'staff']) select.add(new Option(value, value, false, value === person.role));
+      select.onchange = () => act(() => flow(`/api/people/${person.id}`, { method: 'PATCH', body: JSON.stringify({ role: select.value }) }));
+      role.append(select);
+      const toggle = document.createElement('button');
+      toggle.type = 'button';
+      toggle.textContent = person.status === 'active' ? 'Turn off' : person.status === 'pending' ? 'Approve' : 'Turn on';
+      toggle.onclick = () => act(() => flow(`/api/people/${person.id}`, { method: 'PATCH', body: JSON.stringify({ status: person.status === 'active' ? 'disabled' : 'active' }) }));
+      access.append(`${person.status} `, toggle);
+      const remove = document.createElement('button');
+      remove.type = 'button';
+      remove.textContent = 'Remove';
+      remove.onclick = () => { if (confirm(`Remove ${person.email}?`)) act(() => flow(`/api/people/${person.id}`, { method: 'DELETE' })); };
+      actions.append(remove);
+    }
+    tr.append(email, role, access, actions);
+    return tr;
+  });
+  $('people').replaceChildren(...rows);
+}
+</script>
+</body>
+</html>

package/server/core/directory.js

@@ -0,0 +1,39 @@
+import { and, eq, isNull } from 'drizzle-orm';
+import { contacts, organisations, priceItems, CONTACT_KINDS, TAX_CODES } from '../db/schema.js';
+import { FlowError } from './errors.js';
+
+// Organisations, contacts and the price list: the records invoices and bills
+// refer to. Every read and write is scoped to one organisation.
+
+export async function createOrganisation(db, { name, invoicePrefix }) {
+  if (!name?.trim()) throw new FlowError('invalid', 'organisation name is required');
+  const [row] = await db.insert(organisations)
+    .values({ name: name.trim(), ...(invoicePrefix ? { invoicePrefix } : {}) })
+    .returning();
+  return row;
+}
+
+export async function createContact(db, organisationId, { kind, name, email = null }) {
+  if (!CONTACT_KINDS.includes(kind)) throw new FlowError('invalid', `unknown contact kind: ${kind}`);
+  if (!name?.trim()) throw new FlowError('invalid', 'contact name is required');
+  const [row] = await db.insert(contacts)
+    .values({ organisationId, kind, name: name.trim(), email })
+    .returning();
+  return row;
+}
+
+export async function createPriceItem(db, organisationId, { code, name, unitAmountCents, taxCode = 'GST' }) {
+  if (!code?.trim() || !name?.trim()) throw new FlowError('invalid', 'price item code and name are required');
+  if (!Number.isSafeInteger(unitAmountCents)) throw new FlowError('invalid', 'unitAmountCents must be whole cents');
+  if (!TAX_CODES.includes(taxCode)) throw new FlowError('invalid', `unknown tax code: ${taxCode}`);
+  const [row] = await db.insert(priceItems)
+    .values({ organisationId, code: code.trim(), name: name.trim(), unitAmountCents, taxCode })
+    .returning();
+  return row;
+}
+
+export async function listPriceItems(db, organisationId) {
+  return db.select().from(priceItems)
+    .where(and(eq(priceItems.organisationId, organisationId), isNull(priceItems.archivedAt)))
+    .orderBy(priceItems.code);
+}

package/server/core/errors.js

@@ -0,0 +1,11 @@
+// A failure the caller can act on. `code` is stable; the API returns it.
+export class FlowError extends Error {
+  constructor(code, message, details) {
+    super(message);
+    this.name = 'FlowError';
+    this.code = code;
+    if (details !== undefined) this.details = details;
+  }
+}
+
+export const notFound = (what) => new FlowError('not_found', `${what} not found`);