@arcforgelabs/flow 2026.10.50 → 2026.10.51

package/SECURITY.md

@@ -33,8 +33,9 @@ paste a credential, in full or in part.
   organisation, encrypted, and are write-only in Settings.
 - **Records and files.** Every record is in the installation's PostgreSQL.
   Files reach the core only through the object storage port; PostgreSQL
-  holds each file's key, owner, size and hash, and the hash is checked on
-  read. Download links are signed.
+  holds each file's key, owner, size and hash. When Flow serves a file it
+  checks the hash first. Download links are signed. An S3 link is a presigned
+  URL the store itself honours.
 - **Issued documents are records.** An invoice a customer has been sent is
   never changed in place; a change produces a new version.
 
@@ -55,8 +56,12 @@ paste a credential, in full or in part.
   minute, `/api` 120, and the Clerk proxy 300. A client over the limit gets
   `429` with `Retry-After`.
 - Session cookies are `Secure`, `HttpOnly` and `SameSite`.
-- Flow stores no clinical notes, images or scans, and keeps a patient
-  reference only where an invoice must print one.
+- Flow stores no clinical notes or scans, and keeps a patient reference only
+  where an invoice must print one. A form photo is kept only until someone
+  decides the capture, or for 7 days when nobody does, and then the bytes are
+  deleted. The reader sends that photo only to Amazon Bedrock in Sydney or
+  Melbourne, using an `au.` inference profile. Logs and error reports get the
+  capture id and an error code, never the photo or what was read or typed.
 - Object keys and file names carry a case number at most, never a patient
   name or other patient data.
 - CI runs gitleaks on every push and pull request

package/npm-shrinkwrap.json

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

package/package.json

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

package/server/api/captures.js

@@ -0,0 +1,109 @@
+import express from 'express';
+import {
+  MAX_PHOTO_BYTES, captureView, decideCapture, readCapture, readCapturePhoto, typeProposal, uploadCapture,
+} from '../core/captures.js';
+import { FlowError } from '../core/errors.js';
+import { resolveOrganisation } from './invoicing.js';
+
+// Photo capture (server/core/captures.js). A signed-in person uploads one
+// photo. The reader, when it is on, reads it after the response. When it is
+// off, the capture is a problem a person can type. Logs from this router are
+// a capture id and an error code, never the photo or the fields.
+
+const ERROR_STATUS = {
+  not_found: 404,
+  conflict: 409,
+  organisation_required: 409,
+  unsupported_media: 415,
+  photo_too_large: 413,
+  link_invalid: 403,
+  link_expired: 403,
+  storage_unavailable: 503,
+};
+
+function respond(res, error) {
+  return res.status(ERROR_STATUS[error.code] ?? 400).json({ ok: false, code: error.code, error: error.message });
+}
+
+export function createCapturesRouter({ db, storage, personAuth, log = console, publicOrigin = null, reader = null }) {
+  const router = express.Router();
+  const signedIn = [personAuth.requireSession];
+
+  const handle = (fn) => async (req, res) => {
+    try {
+      res.set('Cache-Control', 'no-store');
+      await fn(req, res);
+    } catch (error) {
+      if (!(error instanceof FlowError)) {
+        log.error?.('[captures] - error');
+        return res.status(500).json({ ok: false, code: 'internal', error: 'Something went wrong.' });
+      }
+      if (error.code === 'hash_mismatch' || error.code === 'storage_unavailable') {
+        log.error?.(`[captures] ${error.captureId ?? '-'} ${error.code}`);
+      }
+      if (error.code === 'hash_mismatch') {
+        return res.status(404).json({ ok: false, code: 'not_found', error: 'photo not found' });
+      }
+      return respond(res, error);
+    }
+  };
+
+  const origin = (req) => {
+    const configured = String(publicOrigin ?? '').trim().replace(/\/$/, '');
+    if (configured) return configured;
+    return `${req.protocol}://${req.get('host')}`;
+  };
+  const organisationOf = (req) => resolveOrganisation(db, req.body?.organisationId ?? req.query.organisationId);
+
+  router.get('/file', handle(async (req, res) => {
+    const photo = await readCapturePhoto(db, storage, req.query.token);
+    res.set('Cache-Control', 'private, no-store');
+    res.set('X-Content-Type-Options', 'nosniff');
+    res.set('Content-Type', photo.contentType);
+    res.end(photo.body);
+  }));
+
+  router.post('/', ...signedIn, express.raw({ type: () => true, limit: MAX_PHOTO_BYTES }), handle(async (req, res) => {
+    const organisationId = await organisationOf(req);
+    const result = await uploadCapture(db, storage, organisationId, {
+      bytes: typeof req.body === 'string' || Array.isArray(req.body) || !Buffer.isBuffer(req.body) ? Buffer.alloc(0) : req.body,
+      contentType: req.get('content-type'),
+      idempotencyKey: req.get('idempotency-key'),
+      source: req.get('x-flow-capture-source') ?? req.query.source,
+      personId: req.person.id,
+      baseUrl: origin(req),
+      reader,
+    });
+    res.status(result.created ? 201 : 200).json({ ok: true, capture: captureView(result.capture, result.link) });
+  }));
+
+  router.use(express.json({ limit: '32kb' }));
+
+  router.get('/:id', ...signedIn, handle(async (req, res) => {
+    const result = await readCapture(db, storage, await organisationOf(req), req.params.id, origin(req));
+    res.json({ ok: true, capture: captureView(result.capture, result.link) });
+  }));
+
+  router.post('/:id/proposal', ...signedIn, handle(async (req, res) => {
+    const result = await typeProposal(db, storage, await organisationOf(req), req.params.id, req.body, { baseUrl: origin(req) });
+    res.json({ ok: true, capture: captureView(result.capture, result.link) });
+  }));
+
+  router.post('/:id/decision', ...signedIn, handle(async (req, res) => {
+    const result = await decideCapture(db, storage, await organisationOf(req), req.params.id, req.body?.decision, {
+      personId: req.person.id,
+      baseUrl: origin(req),
+    });
+    res.json({ ok: true, capture: captureView(result.capture, result.link) });
+  }));
+
+  router.use((error, _req, res, next) => {
+    if (error?.type === 'entity.too.large' || error?.status === 413) {
+      return respond(res, new FlowError('photo_too_large', 'photo is too large'));
+    }
+    if (error instanceof FlowError) return respond(res, error);
+    return next(error);
+  });
+
+  return router;
+}

package/server/app.js

@@ -1,5 +1,6 @@
 import express from 'express';
 import { createAlertsRouter } from './api/alerts.js';
+import { createCapturesRouter } from './api/captures.js';
 import { createCustomFieldsRouter } from './api/custom-fields.js';
 import { createWorkMovesRouter } from './api/work-moves.js';
 import { createConnectorApi } from './api/connector.js';
@@ -59,6 +60,13 @@ export function createApp({
   buttonCooldowns = true,
   log = console,
   tracing = null,
+  // Object storage for capture photos (server/core/storage.js). Null leaves
+  // the capture routes off.
+  storage = null,
+  publicOrigin = null,
+  // The vision reader (server/core/reader.js). Null is off: a capture is a
+  // problem a person can type, and no model is called.
+  reader = null,
 } = {}) {
   const app = express();
   app.disable('x-powered-by');
@@ -147,6 +155,11 @@ export function createApp({
     // items, Seazona products).
     const priceSystems = () => integrations?.with('listPriceItems') ?? [];
     app.use('/api/invoicing', createInvoicingRouter({ db: database.db, personAuth: auth.personAuth, log, liveCheckFor, accounting, work, priceSystems, buttonCooldowns }));
+    if (storage) {
+      app.use('/api/captures', createCapturesRouter({
+        db: database.db, storage, personAuth: auth.personAuth, log, publicOrigin, reader,
+      }));
+    }
     // Custom fields for jobs (server/core/custom-fields.js): kept in Flow
     // only; the work systems' statuses show beside them, read only.
     app.use('/api/custom-fields', createCustomFieldsRouter({ db: database.db, personAuth: auth.personAuth, work, log }));

package/server/core/ai-bedrock.js

@@ -0,0 +1,124 @@
+import { createHash } from 'node:crypto';
+import { auProfile, READER_REGIONS } from './ai.js';
+import { FlowError } from './errors.js';
+import { authorizationHeader } from './storage.js';
+
+// Amazon Bedrock, Converse API, Australia only. The endpoint region is
+// Sydney or Melbourne and the model id is an au. inference profile, so a
+// call is not sent on a global or US profile. Credentials come from the
+// caller (the host secret store). Nothing here is logged: a failure keeps
+// the response body out of the error.
+
+const IMAGE_FORMAT = Object.freeze({
+  'image/jpeg': 'jpeg',
+  'image/png': 'png',
+  'image/webp': 'webp',
+  'image/gif': 'gif',
+});
+
+function sha256Hex(body) {
+  return createHash('sha256').update(body).digest('hex');
+}
+
+function amzDate(date) {
+  return date.toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
+}
+
+function fail(code, { retry }) {
+  const error = new FlowError(code, code === 'reader_unavailable' ? 'the reader did not answer' : 'could not read the form');
+  error.retry = retry;
+  return error;
+}
+
+async function drop(res) {
+  await res.arrayBuffer?.().catch(() => {});
+}
+
+// The text blocks only. A thinking block is not the form, and it is not returned.
+function textOf(parsed) {
+  const blocks = parsed?.output?.message?.content;
+  if (!Array.isArray(blocks)) return '';
+  return blocks.filter((block) => typeof block?.text === 'string').map((block) => block.text).join('');
+}
+
+export function createBedrockClient({
+  region, accessKeyId, secretAccessKey, fetchImpl = globalThis.fetch, now = () => new Date(), timeoutMs = 120_000,
+}) {
+  if (!READER_REGIONS.includes(region)) throw new FlowError('invalid', 'reader region must be Sydney or Melbourne');
+  if (!accessKeyId || !secretAccessKey) throw new FlowError('invalid', 'reader credentials are required');
+
+  return {
+    async readImage({ model, mediaType, bytes, instruction, schema, maxTokens = 4096 }) {
+      if (!auProfile(model) || !IMAGE_FORMAT[mediaType] || !Buffer.isBuffer(bytes)) throw fail('reader_rejected', { retry: false });
+      const payload = JSON.stringify({
+        system: [{ text: 'You read one handwritten lab form. You never guess a value.' }],
+        messages: [{
+          role: 'user',
+          content: [
+            { image: { format: IMAGE_FORMAT[mediaType], source: { bytes: bytes.toString('base64') } } },
+            { text: String(instruction ?? '') },
+          ],
+        }],
+        inferenceConfig: { maxTokens },
+        // Effort low keeps the read short. Thinking stays on its default:
+        // Haiku 5.5 and Sonnet 5.5 do not share one way to turn it off.
+        additionalModelRequestFields: { output_config: { effort: 'low' } },
+        outputConfig: {
+          textFormat: {
+            type: 'json_schema',
+            structure: {
+              jsonSchema: {
+                name: 'lab_form',
+                description: 'Fields read from one lab form',
+                schema: JSON.stringify(schema),
+              },
+            },
+          },
+        },
+      });
+      const at = now();
+      const host = `bedrock-runtime.${region}.amazonaws.com`;
+      const path = `/model/${encodeURIComponent(model)}/converse`;
+      const payloadHash = sha256Hex(payload);
+      const headers = {
+        host,
+        'content-type': 'application/json',
+        'x-amz-content-sha256': payloadHash,
+        'x-amz-date': amzDate(at),
+      };
+      const { header } = authorizationHeader({
+        method: 'POST', path, headers, payloadHash, accessKeyId, secretAccessKey, region, service: 'bedrock', now: at,
+      });
+      const sent = { ...headers, authorization: header };
+      delete sent.host;
+      let res;
+      try {
+        res = await fetchImpl(`https://${host}${path}`, {
+          method: 'POST', headers: sent, body: payload, redirect: 'error', signal: AbortSignal.timeout(timeoutMs),
+        });
+      } catch {
+        throw fail('reader_unavailable', { retry: true });
+      }
+      if (!res?.ok) {
+        if (res) await drop(res);
+        const status = res?.status ?? 0;
+        throw fail(status === 429 || status >= 500 ? 'reader_unavailable' : 'reader_rejected', {
+          retry: status === 429 || status >= 500,
+        });
+      }
+      let parsed;
+      try {
+        parsed = JSON.parse(Buffer.from(await res.arrayBuffer()).toString('utf8'));
+      } catch {
+        throw fail('reader_unreadable', { retry: true });
+      }
+      const text = textOf(parsed);
+      if (!text || parsed?.stopReason === 'max_tokens') throw fail('reader_unreadable', { retry: true });
+      return {
+        text,
+        inputTokens: parsed?.usage?.inputTokens ?? 0,
+        outputTokens: parsed?.usage?.outputTokens ?? 0,
+      };
+    },
+  };
+}

package/server/core/ai.js

@@ -0,0 +1,144 @@
+import { FlowError } from './errors.js';
+
+// The AI port. One call reads one image and returns text. The vision reader
+// (server/core/reader.js) is the caller. A client implements readImage; this
+// file does not name a vendor.
+//
+// The model id and the region come from the environment (resolveReader).
+// A model id that is not an Australia inference profile (au.) is refused
+// before any call. An error that leaves this port has a fixed message, so a
+// log never receives the photo or the model's answer.
+
+export const READER_REGIONS = Object.freeze(['ap-southeast-2', 'ap-southeast-4']);
+
+// USD micros per million tokens for the Australia profile: Anthropic's list
+// price plus 10% (October 2026). Haiku 5.5 uses the long rate when the
+// prompt is over 100,000 tokens. An operator sets FLOW_READER_*_MICROS_PER_MILLION
+// when the model id is not listed here, or when the price changes.
+const AU_MICROS = Object.freeze({
+  'au.anthropic.claude-haiku-5-5': Object.freeze({
+    input: 110_000, output: 550_000, longInput: 550_000, longOutput: 2_750_000, longFrom: 100_000,
+  }),
+  'au.anthropic.claude-sonnet-5-5': Object.freeze({ input: 2_200_000, output: 11_000_000 }),
+});
+
+const PROFILE = /^au\.[a-z0-9][a-z0-9._:-]{0,127}$/;
+
+export function auProfile(id) {
+  return typeof id === 'string' && PROFILE.test(id) && !id.includes('..');
+}
+
+// Integer micros for one call. Null when this model has no price: the tokens
+// are still recorded, and the cost is not a guess.
+export function callCostMicros({ inputTokens, outputTokens, price }) {
+  if (!price || !Number.isInteger(inputTokens) || !Number.isInteger(outputTokens)) return null;
+  if (inputTokens < 0 || outputTokens < 0) return null;
+  const long = Number.isInteger(price.longFrom) && inputTokens > price.longFrom;
+  const input = long ? price.longInput : price.input;
+  const output = long ? price.longOutput : price.output;
+  if (!Number.isInteger(input) || !Number.isInteger(output)) return null;
+  return Math.round((inputTokens * input + outputTokens * output) / 1_000_000);
+}
+
+const MESSAGES = Object.freeze({
+  reader_unavailable: 'the reader did not answer',
+  reader_rejected: 'could not read the form',
+  reader_unreadable: 'could not read the form',
+});
+
+function clean(error) {
+  const code = MESSAGES[error?.code] ? error.code : 'reader_unavailable';
+  const next = new FlowError(code, MESSAGES[code]);
+  next.retry = error?.retry !== false && code !== 'reader_rejected';
+  return next;
+}
+
+export function createAiPort(client) {
+  if (typeof client?.readImage !== 'function') throw new TypeError('an AI port needs readImage');
+  return {
+    async readImage(request) {
+      if (!auProfile(request?.model) || !Buffer.isBuffer(request?.bytes) || request.bytes.length === 0) {
+        const error = new FlowError('reader_rejected', MESSAGES.reader_rejected);
+        error.retry = false;
+        throw error;
+      }
+      try {
+        const result = await client.readImage(request);
+        const inputTokens = Number(result?.inputTokens);
+        const outputTokens = Number(result?.outputTokens);
+        return {
+          model: request.model,
+          text: typeof result?.text === 'string' ? result.text : '',
+          inputTokens: Number.isInteger(inputTokens) && inputTokens >= 0 ? inputTokens : 0,
+          outputTokens: Number.isInteger(outputTokens) && outputTokens >= 0 ? outputTokens : 0,
+        };
+      } catch (error) {
+        throw clean(error);
+      }
+    },
+  };
+}
+
+function readMicros(raw, name) {
+  if (raw == null || String(raw).trim() === '') return null;
+  const value = Number(String(raw).trim());
+  if (!Number.isInteger(value) || value < 0) throw new Error(`${name} must be a whole number of micros per million tokens`);
+  return value;
+}
+
+function priceFrom(env, model, prefix) {
+  const input = readMicros(env[`${prefix}_INPUT_MICROS_PER_MILLION`], `${prefix}_INPUT_MICROS_PER_MILLION`);
+  const output = readMicros(env[`${prefix}_OUTPUT_MICROS_PER_MILLION`], `${prefix}_OUTPUT_MICROS_PER_MILLION`);
+  if (input == null && output == null) return AU_MICROS[model] ?? null;
+  if (input == null || output == null) {
+    throw new Error(`${prefix}_INPUT_MICROS_PER_MILLION and ${prefix}_OUTPUT_MICROS_PER_MILLION are set together`);
+  }
+  return { input, output };
+}
+
+function sureLineOf(env) {
+  const raw = String(env.FLOW_READER_SURE_LINE ?? '').trim();
+  if (!raw) return 0.8;
+  const value = Number(raw);
+  if (!Number.isFinite(value) || value < 0 || value > 1) throw new Error('FLOW_READER_SURE_LINE must be a number from 0 to 1');
+  return value;
+}
+
+// Answers the reader settings. `on` is false when the module is off or the
+// keys are missing: a capture is then a problem a person can type. A region
+// outside Sydney and Melbourne, or a model id that is not an au. profile,
+// stops boot rather than sending a form there.
+export function resolveReader({ env = process.env } = {}) {
+  const flag = String(env.FLOW_READER ?? '').trim().toLowerCase();
+  if (flag && flag !== 'on' && flag !== 'off') throw new Error('FLOW_READER must be "on", "off" or unset');
+  if (flag !== 'on') return { on: false, reason: flag === 'off' ? 'off' : 'unset' };
+
+  const region = String(env.FLOW_READER_REGION ?? '').trim();
+  const model = String(env.FLOW_READER_MODEL ?? '').trim();
+  const large = String(env.FLOW_READER_MODEL_LARGE ?? '').trim();
+  if (!READER_REGIONS.includes(region)) {
+    throw new Error('FLOW_READER=on needs FLOW_READER_REGION set to ap-southeast-2 (Sydney) or ap-southeast-4 (Melbourne)');
+  }
+  if (!model || !large) throw new Error('FLOW_READER=on needs FLOW_READER_MODEL and FLOW_READER_MODEL_LARGE');
+  if (!auProfile(model) || !auProfile(large)) {
+    throw new Error('FLOW_READER_MODEL and FLOW_READER_MODEL_LARGE must be au. inference profiles');
+  }
+  const accessKeyId = String(env.FLOW_READER_ACCESS_KEY_ID ?? '').trim();
+  const secretAccessKey = String(env.FLOW_READER_SECRET_ACCESS_KEY ?? '').trim();
+  if (!accessKeyId || !secretAccessKey) return { on: false, reason: 'no_credentials' };
+
+  return {
+    on: true,
+    reason: null,
+    region,
+    model,
+    large,
+    accessKeyId,
+    secretAccessKey,
+    sureLine: sureLineOf(env),
+    prices: {
+      small: priceFrom(env, model, 'FLOW_READER'),
+      large: priceFrom(env, large, 'FLOW_READER_LARGE'),
+    },
+  };
+}