biz-a-cli 2.3.80-15271 → 2.3.80-15280

package/bin/directHubEvent.js

@@ -4,6 +4,8 @@ import { Tunnel as QuickTunnel } from "cloudflared";
 import { Server as ioServer } from "socket.io";
 import { CLIENT_ROOM } from "../message-broker/clientEmitter.js";
 import { ClientEmitter } from "../message-broker/clientEmitter.js";
+import { joinExtRooms } from "../engine/ext/esb.js";
+import { extClientListener } from "../engine/ext/socketListener.js";
 
 export async function localhostTunnel(port, notifier) {
 	let tunnelUrl = "";
@@ -67,27 +69,40 @@ export function directHubEvent(serverSocket, argv) {
 
 		if (clientSocket.handshake.query.isClient) {
 			setConnectListeners(clientSocket);
-			clientListener(clientSocket, argv);
-			clientSocket.join(CLIENT_ROOM);
 
-			// isolated Client in a room using clientInstanceId
-			const clientInstanceId =
-				clientSocket.handshake.query.clientInstanceId;
-			if (clientInstanceId) {
-				clientSocket.join(clientInstanceId);
-				clientSocket.on("ESB_ACK", (msgId) => {
-					ClientEmitter.acknowledgeMessage(msgId, clientInstanceId);
-				});
-			}
+			const extToken = clientSocket.handshake.query.extToken;
+			const extSlug = clientSocket.handshake.query.extSlug;
+			if (extToken && extSlug) {
+				// EXTERNAL client: RESTRICTED listener (runExtCliScript only — no apiRequest /
+				// runcliscript / engine / emitter), and rooms derived from the VERIFIED token
+				// only (a forged userId/slug in the handshake is ignored). It does NOT join
+				// CLIENT_ROOM (internal broadcasts).
+				extClientListener(clientSocket, argv);
+				joinExtRooms(clientSocket, extToken, { slug: extSlug });
+			} else {
+				// INTERNAL client — full listener + existing rooms, unchanged.
+				clientListener(clientSocket, argv);
+				clientSocket.join(CLIENT_ROOM);
+
+				// isolated Client in a room using clientInstanceId
+				const clientInstanceId =
+					clientSocket.handshake.query.clientInstanceId;
+				if (clientInstanceId) {
+					clientSocket.join(clientInstanceId);
+					clientSocket.on("ESB_ACK", (msgId) => {
+						ClientEmitter.acknowledgeMessage(msgId, clientInstanceId);
+					});
+				}
 
-			// isolated Client in a room using argv.subdomain and UserId
-			const userId = clientSocket.handshake.query.userId;
-			if (
-				userId !== undefined &&
-				userId !== null &&
-				String(userId) !== "-1"
-			) {
-				clientSocket.join(`${argv.subdomain}_USER_${userId}`);
+				// isolated Client in a room using argv.subdomain and UserId
+				const userId = clientSocket.handshake.query.userId;
+				if (
+					userId !== undefined &&
+					userId !== null &&
+					String(userId) !== "-1"
+				) {
+					clientSocket.join(`${argv.subdomain}_USER_${userId}`);
+				}
 			}
 		} else if (clientSocket.handshake.query.isDeploy) {
 			setConnectListeners(clientSocket);

package/bin/hub.js

@@ -199,6 +199,8 @@ import http from "http";
 import https from "https";
 import path from "node:path";
 import bpmRoutes from "../engine/bpm/routes.js";
+import { createExtRouter } from "../engine/ext/routes.js";
+import { createLiveExtDeps } from "../engine/ext/live.js";
 
 app.use(compression());
 app.use(cors());
@@ -218,6 +220,44 @@ app.use("/status", (req, res) => {
 
 app.use("/bpm", bpmRoutes);
 
+// External Access boundary (§ Biz-A External Access). Same process as the internal
+// endpoints, but a narrow allowlist: anonymous entry + published-operation dispatch only.
+// Single-tenant live wiring over this hub's own Firebird (argv.subdomain / argv.dbindex);
+// requires the `ext.capability` secret + authored SYS$EXT_* / SYS$APPS rows to serve.
+let extOidcConfig;
+try {
+	extOidcConfig = JSON.parse(
+		fs.readFileSync(
+			path.join(process.cwd(), "config", "ext-oidc.json"),
+			"utf8",
+		),
+	);
+} catch {
+	extOidcConfig = undefined; // no federated providers configured -> anonymous-only
+}
+const extDeps = createLiveExtDeps({
+	subdomain: argv.subdomain,
+	dbindex: argv.dbindex,
+	finaDbIndex: argv.finaDbindex,
+	apiUrl: `http://${argv.hostname}:${argv.port}`,
+	oidc: extOidcConfig,
+});
+app.use(
+	"/ext/:slug",
+	createExtRouter({
+		getManifest: extDeps.getManifest,
+		getAppBundle: extDeps.getAppBundle,
+		auditSink: extDeps.auditSink,
+		oidc: extDeps.oidc,
+		identityStore: extDeps.identityStore,
+		resolveTenant: extDeps.resolveTenant,
+		getChannelInfo: () => {
+			const a = argv.cliAddress ? argv.cliAddress() : {};
+			return { cliAddress: a.publicUrl, hubAddress: a.hubUrl };
+		},
+	}),
+);
+
 // create HTTP(s) Server
 const keyFile = path.join(import.meta.dirname, "../cert/key.pem");
 const certFile = path.join(import.meta.dirname, "../cert/cert.pem");

package/bin/hubEvent.js

@@ -11,6 +11,9 @@ const packageJson = require("../package.json");
 import { deploymentListenerForHubServer } from "./deployEvent.js";
 import { execCLIScriptWorker, workerStats } from "../worker/cliWorkerPool.js";
 import { ClientEmitter } from "../message-broker/clientEmitter.js";
+import { handleRunExtCliScript } from "../engine/ext/channel.js";
+import { extDeriveRoomsHandler } from "../engine/ext/esb.js";
+import { makeExtReqHandler } from "../engine/ext/hubProxy.js";
 
 export const IDLE_SOCKET_TIMEOUT_MILLISECONDS = 1000 * 28;
 export const RECONNECT_SOCKET_DELAY = 60 * 1000;
@@ -165,9 +168,19 @@ export const streamEvent = async (socket, argv) =>
 			}
 		};
 
+		// External Access: biz-a relays `/ext/:slug/*` here (routed by subdomain) so the CLI's ext
+		// boundary is reachable through biz-a without exposing the CLI to the browser. Unlike cli-req
+		// (which targets /cb), this forwards to the FULL path on the CLI's own express + preserves status.
+		const extReqCb = makeExtReqHandler({
+			request: (opts) => axios.request(opts),
+			baseUrl: () =>
+				`${process.env.HOST || "http://localhost"}:${argv.serverport}`,
+		});
+
 		socket.on("connect", connectCb);
 		socket.on("incomingClient", incomingHubCb);
 		socket.on("cli-req", cliReqCb);
+		socket.on("ext-req", extReqCb);
 		socket.on("cliCommand", (data, cb) => handleCliCommand(data, cb, argv));
 
 		socket.on("disconnect", (reason) => {
@@ -234,6 +247,12 @@ export const hubEvent = (socket, argv, notifier) => {
 		ClientEmitter.acknowledgeMessage(msgId, clientInstanceId);
 	});
 
+	// Hub-channel external real-time: the biz-a hub cannot verify a capability token, so it asks
+	// this CLI (which owns the ext secret) to derive an external client's rooms; we verify and ack
+	// the room list, and the hub joins the client to exactly those (forged/cross-slug token -> []).
+	socket.on("extDeriveRooms", extDeriveRoomsHandler);
+	// (Removed) extAuthCallback relay — sign-in is now client-orchestrated (see engine/ext/channel.js).
+
 	return socket;
 };
 
@@ -337,6 +356,13 @@ const handleCliCommand = async (data, cb, argv) => {
 					),
 				);
 				break;
+			case "runextcliscript": {
+				// External-access op invoker — enforces the capability boundary (dispatch.js),
+				// unlike raw `runcliscript`. Safe to expose: no valid token -> UNAUTHENTICATED.
+				const r = await handleRunExtCliScript(data, argv);
+				cb(r.error || null, r.error ? null : r.data);
+				break;
+			}
 			case "engine": {
 				// Ex: Extracts "bpm/instance" and "initiate" from "bpm/instance/initiate"
 				const targetParts = data.target.split("/");

package/engine/ext/appStore.js

@@ -0,0 +1,27 @@
+// Delivers the tenant's external app bundle: the SYS$APPS rows (metadata + the packaged
+// TEMPLATES blob) for exactly the apps the manifest references — the distinct APP_IDs on its
+// published operations. No new "external app" flag is needed; the manifest already names the
+// apps in play. The client caches + expands these into its slug-scoped IndexedDB, reusing
+// the existing template pipeline.
+//
+// resolveTenant(slug) -> { dbindex, ... } | null  (CDM slug resolver)
+// loadManifest(slug)  -> manifest | null
+// readApps(tenant, appIds) -> [{ appName, metadata, templates, updatedAt }]  (SYS$APPS read)
+export function createAppBundleLoader({ resolveTenant, loadManifest, readApps }) {
+	async function getAppBundle(slug) {
+		const tenant = await resolveTenant(slug);
+		if (!tenant) return null; // unknown slug -> 404 (never reads apps)
+
+		const manifest = await loadManifest(slug);
+		const ops =
+			manifest && manifest.operations
+				? Object.values(manifest.operations)
+				: [];
+		const appIds = [...new Set(ops.map((o) => o.appId).filter(Boolean))];
+		if (!appIds.length) return { apps: [] };
+
+		const apps = await readApps(tenant, appIds);
+		return { apps: apps || [] };
+	}
+	return { getAppBundle };
+}

package/engine/ext/cdmClient.js

@@ -0,0 +1,35 @@
+// CDM (Customer Database Manager) client for slug -> tenant resolution.
+//
+// CDM is the same license service that backs internal login (biz-a signInToCDM ->
+// `${cdmAddr}/company/signIn`). For external access it exposes a PUBLIC, credential-less
+// resolution of a slug (= companyID, public per D-5) to its tenant descriptor:
+//     GET `${cdmAddr}/company/resolve/{slug}` -> { success, data: { companyId, companyName, subdomain } }
+// (added in cdm/controllers/company.js + routers/company.js).
+//
+// The cli hub is single-tenant — it already knows its own dbindex/subdomain from argv — so
+// CDM only vouches for the slug and yields its subdomain; the hub supplies dbindex. This
+// client merges the two into the tenant shape the slug resolver expects. Fail-closed:
+// unknown slug (or subdomain mismatch, when the hub's subdomain is known) -> null.
+import axios from "axios";
+
+export function makeCdmClient({ cdmAddr, http = axios, dbindex, finaDbIndex, subdomain }) {
+	return {
+		async resolveTenant(slug) {
+			const res = await http.get(
+				`${cdmAddr}/company/resolve/${encodeURIComponent(slug)}`,
+			);
+			const d = res && res.data;
+			if (!d || d.success === false || !d.data) return null;
+			const t = d.data;
+			const resolvedSubdomain = t.subdomain || t.companyId || slug;
+			// This hub serves exactly one tenant; reject a slug that resolves elsewhere.
+			if (subdomain && resolvedSubdomain !== subdomain) return null;
+			return {
+				company: t.companyId || t.companyName || slug,
+				subdomain: resolvedSubdomain,
+				dbindex, // from the hub's own config (argv.dbindex)
+				finaDbIndex,
+			};
+		},
+	};
+}

package/engine/ext/channel.js

@@ -0,0 +1,75 @@
+// runExtCliScript — the CHANNEL-based external operation invoker (the socket equivalent of
+// POST /ext/{slug}/op/{name}). The external client (or biz-a) reaches the cli over the existing
+// socket channels via cliCommand, so external ops don't need a dedicated HTTP /ext proxy.
+//
+// CRUCIAL: this is NOT the plain `runcliscript` command, which runs any named script with the
+// hub's own identity. It runs through the SHARED external dispatch core (dispatch.js), so the
+// exact same enforcement as the HTTP boundary applies — capability verification, manifest lookup,
+// tier gate, RESPONSE_FIELDS, audit. A caller with no valid capability token gets UNAUTHENTICATED.
+import fs from "node:fs";
+import path from "node:path";
+import { makeExtDispatch } from "./dispatch.js";
+
+let _deps = null;
+let _dispatch = null;
+
+// Build + cache the LIVE ext deps from the hub's argv (the same deps the HTTP boundary uses).
+// live.js is imported LAZILY here so that merely importing this module (e.g. via hubEvent) does
+// NOT pull live.js's db/db.js + worker-pool graph into unrelated test/module contexts — it
+// loads only when an external channel request actually arrives.
+async function getLiveDeps(argv) {
+	if (_deps) return _deps;
+	const { createLiveExtDeps } = await import("./live.js");
+	let oidcConfig;
+	try {
+		oidcConfig = JSON.parse(
+			fs.readFileSync(
+				path.join(process.cwd(), "config", "ext-oidc.json"),
+				"utf8",
+			),
+		);
+	} catch {
+		oidcConfig = undefined;
+	}
+	_deps = createLiveExtDeps({
+		subdomain: argv.subdomain,
+		dbindex: argv.dbindex,
+		finaDbIndex: argv.finaDbindex,
+		apiUrl: `http://${argv.hostname}:${argv.port}`,
+		oidc: oidcConfig,
+	});
+	return _deps;
+}
+
+// Build + cache the dispatch core from the live deps.
+async function getExtDispatch(argv) {
+	if (_dispatch) return _dispatch;
+	const deps = await getLiveDeps(argv);
+	_dispatch = makeExtDispatch({
+		getManifest: deps.getManifest,
+		auditSink: deps.auditSink,
+	});
+	return _dispatch;
+}
+
+// cliCommand data: { command:'runExtCliScript', slug, token, op, params }. Returns { data } or
+// { error } (API-6). `dispatch` is injectable for testing.
+export async function handleRunExtCliScript(data, argv, dispatch) {
+	const d = dispatch || (await getExtDispatch(argv));
+	return d.invokeOp({
+		slug: data.slug,
+		token: data.token,
+		name: data.op,
+		body: data.params,
+	});
+}
+
+// (Removed) OAuth callback OVER CHANNEL — sign-in is now CLIENT-orchestrated: the provider redirect
+// lands on the app's own tenant-agnostic route, and the client completes the code exchange via the
+// HTTP /ext/{slug}/auth/exchange endpoint. biz-a no longer relays the callback.
+
+// test hook — drop the cached dispatch + live deps
+export function _resetExtDispatch() {
+	_dispatch = null;
+	_deps = null;
+}

package/engine/ext/cliInvoke.js

@@ -0,0 +1,23 @@
+// M6 — CLI-backed operation execution.
+//
+// Runs ONLY the operation's OWN declared script (op.scriptRef — never a caller-named one),
+// with a SERVER-DERIVED principal: an EXTERNAL actor carrying NO roles and no transition. The
+// caller's op params are passed as inert DATA, so a body field like `userRoles` or
+// `transition` can never become an authorization input. This is deliberately NOT the internal
+// cliCommand/engine dispatch (hubEvent.js), which trusts caller-supplied identity/roles.
+//
+// `runScript(scriptRef, params, principal)` is injected — the live wiring runs the named
+// script via the worker pool (execCLIScriptWorker), scoped to the tenant. RESPONSE_FIELDS is
+// enforced by the router on whatever the script returns.
+export function externalPrincipal(claims) {
+	return {
+		actorType: "EXTERNAL",
+		extUserId: claims?.uid ?? null,
+		roles: [], // never caller-supplied
+	};
+}
+
+export async function executeCliOp(op, params, claims, runScript) {
+	if (!op || !op.scriptRef) throw new Error("NO_SCRIPT");
+	return runScript(op.scriptRef, params || {}, externalPrincipal(claims));
+}

package/engine/ext/dispatch.js

@@ -0,0 +1,91 @@
+// Transport-agnostic external operation dispatch.
+//
+// The security enforcement of the External Access boundary — capability verification, manifest
+// lookup, tier gate, RESPONSE_FIELDS, audit — lives HERE, in one place, so it is identical
+// whether a request arrives over HTTP (routes.js /ext/op) or over a socket channel
+// (runExtCliScript). invokeOp returns { data } on success or { error } from the stable API-6 set;
+// the caller maps that to its transport (HTTP status code / socket callback).
+import { verifyCapability, tierMeets } from "./token.js";
+import { resolveOperation } from "./manifest.js";
+import { applyResponseFields } from "./responseFields.js";
+
+export const EXT_ERROR_STATUS = {
+	UNAUTHENTICATED: 401,
+	FORBIDDEN: 403,
+	NOT_FOUND: 404,
+	RATE_LIMITED: 429,
+	INVALID_PARAMS: 400,
+	PROVIDER_UNAVAILABLE: 400,
+};
+
+export function makeExtDispatch({ getManifest, auditSink }) {
+	async function loadManifest(slug) {
+		try {
+			return await getManifest(slug);
+		} catch {
+			return null;
+		}
+	}
+
+	// The caller has already established the token is present (surface classification is a
+	// transport concern); here we VERIFY it and run the operation.
+	async function invokeOp({ slug, token, name, body }) {
+		const claims = verifyCapability(token, { slug });
+		if (!claims) return { error: "UNAUTHENTICATED" };
+
+		const audit = (outcome, op) => {
+			if (!auditSink) return;
+			try {
+				auditSink({
+					slug,
+					opName: name,
+					actorTier: claims.tier,
+					actorExtUserId: claims.uid ?? null,
+					appId: op?.appId ?? null,
+					outcome,
+				});
+			} catch {
+				// audit must never break a request
+			}
+		};
+
+		const manifest = await loadManifest(slug);
+		const op = manifest ? resolveOperation(manifest, name) : null;
+		if (!op) {
+			audit("NOT_FOUND");
+			return { error: "NOT_FOUND" };
+		}
+		if (!tierMeets(claims.tier, op.minTier)) {
+			audit("UNAUTHENTICATED", op);
+			return { error: "UNAUTHENTICATED" };
+		}
+		if (op.kind !== "DECLARATIVE" && op.kind !== "CLI") {
+			audit("INVALID_PARAMS", op);
+			return { error: "INVALID_PARAMS" };
+		}
+
+		let data;
+		try {
+			data =
+				typeof op.resolve === "function"
+					? await op.resolve(body || {}, claims)
+					: null;
+		} catch {
+			audit("INVALID_PARAMS", op);
+			return { error: "INVALID_PARAMS" };
+		}
+		audit("OK", op);
+		// A CLI op may return an EFFECTS envelope { effects:[...] } — the client's effect engine
+		// applies these verbatim (FORM_PATCH / NOTIF / NAVIGATE / …). The op's OWN server-authored
+		// script is the boundary for what those effects carry, so they are NOT run through the
+		// data-field RESPONSE_FIELDS allowlist (which governs client-param-driven read shapes).
+		// DECLARATIVE ops are always data-only and field-filtered — an `effects` key there is plain
+		// data, not an envelope.
+		if (op.kind === "CLI" && data && Array.isArray(data.effects)) {
+			return { data: { effects: data.effects } };
+		}
+		return { data: applyResponseFields(op.responseFields, data) };
+	}
+
+	return { invokeOp, loadManifest };
+}

package/engine/ext/esb.js

@@ -0,0 +1,84 @@
+// M9 — authenticated ESB for external real-time.
+//
+// The internal ESB joins rooms from the socket handshake query (subdomain/userId/
+// clientInstanceId), which an external caller could forge to receive another tenant's or
+// user's events. For external clients the rooms are instead DERIVED from the VERIFIED
+// capability token: a client only ever lands in its own tenant room (and, once signed in, its
+// own user room). A forged/absent/cross-slug token joins nothing.
+import crypto from "node:crypto";
+import { verifyCapability } from "./token.js";
+
+export function extRoom(slug) {
+	return `EXT_${slug}`;
+}
+export function extUserRoom(slug, extUserId) {
+	return `EXT_${slug}_USER_${extUserId}`;
+}
+
+// Rooms an external client may join, from the verified token. Invalid/forged/cross-slug -> [].
+export function deriveExtRooms(token, { slug } = {}) {
+	const claims = verifyCapability(token, { slug });
+	if (!claims) return [];
+	const rooms = [extRoom(claims.slug)];
+	if (claims.tier === "T1" && claims.uid != null) {
+		rooms.push(extUserRoom(claims.slug, claims.uid));
+	}
+	return rooms;
+}
+
+// Join the derived rooms on a socket (ignoring anything the handshake asserts). Returns the
+// rooms joined ([] if the token is invalid).
+export function joinExtRooms(socket, token, opts = {}) {
+	const rooms = deriveExtRooms(token, opts);
+	for (const r of rooms) socket.join(r);
+	return rooms;
+}
+
+// Emit helpers targeting the external rooms. Payload is wrapped like the internal ESB
+// (msgId/timestamp/data) for a uniform client contract.
+//
+// `relaySocket` (the CLI's socket TO the biz-a hub) is optional: when supplied and connected, the
+// SAME wrapped message is ALSO relayed to the hub as `extRelay {room, eventName, message}`, so
+// external clients connected through the hub channel (not this CLI's own direct-hub server)
+// receive it too. biz-a fans it out room-agnostically — the room name and wrap shape are owned
+// here (single-sourced), so the hub never needs to know the EXT_* naming convention. This mirrors
+// the internal broadcastToClient/emitToClient hub relay in clientEmitter.js.
+export function makeExtEmitter(ioServerInstance, relaySocket) {
+	const wrap = (payload) => ({
+		msgId: crypto.randomUUID(),
+		timestamp: Date.now(),
+		data: payload,
+	});
+	const send = (room, eventName, payload) => {
+		const message = wrap(payload); // wrap ONCE — one msgId across both transports
+		if (ioServerInstance) {
+			ioServerInstance.to(room).emit(eventName, message);
+		}
+		if (relaySocket && relaySocket.connected) {
+			relaySocket.emit("extRelay", { room, eventName, message });
+		}
+	};
+	return {
+		broadcastExt(slug, eventName, payload) {
+			send(extRoom(slug), eventName, payload);
+		},
+		emitExtUser(slug, extUserId, eventName, payload) {
+			send(extUserRoom(slug, extUserId), eventName, payload);
+		},
+	};
+}
+
+// Registered by the CLI on its socket TO the biz-a hub. The hub cannot verify a capability token
+// (it holds no ext secret), so when an external client connects through the hub channel the hub
+// asks the tenant CLI — which owns the secret — to derive that client's rooms. The CLI verifies
+// and acks the room list; the hub then joins the client to exactly those rooms. A forged/absent/
+// cross-slug token yields [] (no rooms), so the hub channel is as forgery-proof as the direct one.
+export function extDeriveRoomsHandler(data, ack) {
+	let rooms = [];
+	try {
+		rooms = deriveExtRooms(data?.token, { slug: data?.slug });
+	} catch {
+		rooms = [];
+	}
+	if (typeof ack === "function") ack(null, rooms);
+}

package/engine/ext/hubProxy.js

@@ -0,0 +1,49 @@
+// Slice 1 — CLI-side forwarder for external HTTP relayed from biz-a over the hub socket.
+//
+// In production the tenant CLI never faces the browser: an external request lands on biz-a
+// (`/ext/:slug/*`), biz-a resolves slug -> subdomain and relays it to THIS CLI as an `ext-req`
+// socket event, and this handler re-issues it against the CLI's OWN /ext express router. It mirrors
+// the `/cb` `cli-req` forwarder (bin/hubEvent.js) but with two differences the external boundary
+// requires: it preserves the FULL path (no `/cb` prefix) so `/ext/{slug}/…` hits the ext router, and
+// it preserves the response STATUS (the boundary returns 401/404/429/400 as real answers, not throws).
+//
+// Only the headers the boundary needs are forwarded — the capability token, the content type, and the
+// real client IP (for the per-IP rate limiter) — so internal headers (cookies, authorizedtoken) never
+// leak across the boundary.
+const EXT_HEADER_ALLOWLIST = ["x-ext-capability", "content-type", "x-forwarded-for"];
+
+export function makeExtReqHandler({ request, baseUrl }) {
+	return async (data, callback) => {
+		const { path, method, query, body, headers } = data || {};
+		const src = headers || {};
+		const fwd = {};
+		for (const name of EXT_HEADER_ALLOWLIST) {
+			// header maps arrive lowercased from express; guard the odd upper-cased relay too.
+			const v = src[name] ?? src[name.toUpperCase()];
+			if (v != null && v !== "") fwd[name] = v;
+		}
+		try {
+			const res = await request({
+				method: method || "GET",
+				url: `${baseUrl()}${path || ""}`,
+				params: query || {},
+				data: body,
+				headers: fwd,
+				// 4xx from the boundary are real responses to relay, not exceptions to swallow.
+				validateStatus: () => true,
+			});
+			const rh = res.headers || {};
+			const contentType =
+				(typeof rh.get === "function" ? rh.get("content-type") : rh["content-type"]) ||
+				"application/json";
+			callback({ status: res.status, contentType, body: res.data });
+		} catch {
+			// CLI express unreachable — surface a stable 502 to biz-a (which relays it to the browser).
+			callback({
+				status: 502,
+				contentType: "application/json",
+				body: { error: "PROXY_UNAVAILABLE" },
+			});
+		}
+	};
+}

package/engine/ext/identityRepo.js

@@ -0,0 +1,74 @@
+// M7 live — DB-backed identity repo behind createIdentityStore (identityStore.js). Implements
+// the four repo methods over injected query/write/genId (wired to db/db.js + datalib genId in
+// live.js), so it needs no database to test. SYS$EXT_USER ids are pre-generated with genId so
+// the new id is known without relying on an insert to return it.
+export function createLiveIdentityRepo({ query, write, genId }) {
+	// SQL string literal, single quotes doubled (the queryData filter interpolates value1).
+	const lit = (s) => `'${String(s).replace(/'/g, "''")}'`;
+
+	return {
+		async findIdentity(tenant, provider, subject) {
+			const rows = await query(tenant, {
+				length: 1,
+				filter: [
+					{
+						junction: "",
+						column: "SYS$EXT_USER_IDENTITY.PROVIDER",
+						operator: "=",
+						value1: lit(provider),
+					},
+					{
+						junction: "AND",
+						column: "SYS$EXT_USER_IDENTITY.PROVIDER_SUBJECT",
+						operator: "=",
+						value1: lit(subject),
+					},
+				],
+				columns: [
+					{
+						data: "SYS$EXT_USER_IDENTITY.SYS$EXT_USER_ID",
+						key: "ext_user_id",
+					},
+				],
+			});
+			return rows && rows[0] ? { ext_user_id: rows[0].ext_user_id } : null;
+		},
+
+		async createUser(tenant, { label }) {
+			const id = await genId(tenant, "SYS$EXT_USER_GEN");
+			await write(tenant, "SYS$EXT_USER", {
+				id,
+				label: label ?? null,
+				status: "ACTIVE",
+			});
+			return id;
+		},
+
+		async linkIdentity(tenant, { extUserId, provider, subject }) {
+			await write(tenant, "SYS$EXT_USER_IDENTITY", {
+				SYS$EXT_USER_ID: extUserId,
+				provider,
+				provider_subject: subject,
+			});
+		},
+
+		async getUser(tenant, extUserId) {
+			const rows = await query(tenant, {
+				length: 1,
+				filter: [
+					{
+						junction: "",
+						column: "SYS$EXT_USER.ID",
+						operator: "=",
+						value1: extUserId,
+					},
+				],
+				columns: [
+					{ data: "SYS$EXT_USER.ID", key: "id" },
+					{ data: "SYS$EXT_USER.LABEL", key: "label" },
+				],
+			});
+			return rows && rows[0] ? rows[0] : null;
+		},
+	};
+}

package/engine/ext/identityStore.js

@@ -0,0 +1,25 @@
+// External-user identity store (federated only — no stored credentials). Resolves a
+// (provider, subject) pair to a SYS$EXT_USER, creating the user + SYS$EXT_USER_IDENTITY link
+// on first sight (XI). The DB repo is injected so this is testable without a database; the
+// live repo wraps db/ds scoped to the tenant's dbindex.
+export function createIdentityStore({ repo }) {
+	return {
+		// Returns { extUserId, created }. `created` is true only on first sight of the subject.
+		async resolveOrCreateUser(tenant, { provider, subject, email }) {
+			const existing = await repo.findIdentity(tenant, provider, subject);
+			if (existing) {
+				return { extUserId: existing.ext_user_id, created: false };
+			}
+			const extUserId = await repo.createUser(tenant, {
+				label: email || null,
+			});
+			await repo.linkIdentity(tenant, { extUserId, provider, subject });
+			return { extUserId, created: true };
+		},
+
+		// The caller's own record (XI-28: no listing/search — scoped to one ext user id).
+		async getUser(tenant, extUserId) {
+			return repo.getUser(tenant, extUserId);
+		},
+	};
+}