@prosopo/provider-mock 2.8.141 → 2.8.144

package/dist/verify.js

@@ -0,0 +1,34 @@
+//#region src/verify.ts
+/**
+* The fixtures this mock provider treats as already verified.
+*
+* They are the accounts and commitment the integration suites sign with; any
+* token carrying one of them is approved without a captcha ever being solved,
+* which is the whole point of the mock.
+*/
+var TEST_COMMITMENT_ID = "0x123456789test";
+var TEST_ACCOUNT = "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY";
+var TEST_DAPP = "5C4hrfjw9DjXZTzV3MwzrrAr9P1MJhSrvWGWqi1eSuyUpnhM";
+var VERIFIED_MESSAGE = "API.USER_VERIFIED";
+var NOT_VERIFIED_MESSAGE = "API.USER_NOT_VERIFIED";
+/**
+* Decide whether a decoded token counts as verified.
+*
+* Any one of the three fixtures matching is enough — a token only carries the
+* fields the client filled in, so requiring all three would never approve.
+* Empty strings are not matches: an absent field decodes to "" and must not be
+* able to satisfy a comparison against a fixture.
+*/
+var verifyProcaptchaOutput = (output) => {
+	if (!(output.user === "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY" || output.commitmentId === "0x123456789test" || output.dapp === "5C4hrfjw9DjXZTzV3MwzrrAr9P1MJhSrvWGWqi1eSuyUpnhM")) return {
+		statusMessage: NOT_VERIFIED_MESSAGE,
+		verified: false
+	};
+	return {
+		statusMessage: VERIFIED_MESSAGE,
+		verified: true,
+		commitmentId: TEST_COMMITMENT_ID
+	};
+};
+//#endregion
+export { NOT_VERIFIED_MESSAGE, TEST_ACCOUNT, TEST_COMMITMENT_ID, TEST_DAPP, VERIFIED_MESSAGE, verifyProcaptchaOutput };

package/dist/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AAuBA,MAAM,CAAC,MAAM,kBAAkB,GAAG,iBAAiB,CAAC;AACpD,MAAM,CAAC,MAAM,YAAY,GAAG,kDAAkD,CAAC;AAC/E,MAAM,CAAC,MAAM,SAAS,GAAG,kDAAkD,CAAC;AAE5E,MAAM,CAAC,MAAM,gBAAgB,GAAG,mBAAmB,CAAC;AACpD,MAAM,CAAC,MAAM,oBAAoB,GAAG,uBAAuB,CAAC;AAiB5D,MAAM,CAAC,MAAM,sBAAsB,GAAG,CACrC,MAAgE,EAC1C,EAAE;IACxB,MAAM,OAAO,GACZ,MAAM,CAAC,IAAI,KAAK,YAAY;QAC5B,MAAM,CAAC,YAAY,KAAK,kBAAkB;QAC1C,MAAM,CAAC,IAAI,KAAK,SAAS,CAAC;IAE3B,IAAI,CAAC,OAAO,EAAE,CAAC;QACd,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IACjE,CAAC;IAED,OAAO;QACN,aAAa,EAAE,gBAAgB;QAC/B,QAAQ,EAAE,IAAI;QACd,YAAY,EAAE,kBAAkB;KAChC,CAAC;AACH,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@prosopo/provider-mock",
-	"version": "2.8.141",
+	"version": "2.8.144",
 	"author": "PROSOPO LIMITED <info@prosopo.io>",
 	"license": "Apache-2.0",
 	"type": "module",
@@ -22,21 +22,28 @@
 		"build:cross-env": "vite build --config vite.esm.config.ts",
 		"build:tsc": "tsc --build --verbose",
 		"build:cjs": "NODE_ENV=${NODE_ENV:-development}; vite build --config vite.cjs.config.ts --mode $NODE_ENV",
+		"docker-tag": "node ../../docker/docker-tag.mjs",
+		"build:docker": "docker buildx build --progress=plain --tag $(npm run --silent docker-tag) --platform linux/amd64 -f ./Dockerfile ../..",
+		"publish:docker": "docker push $(npm run --silent docker-tag)",
 		"typecheck": "tsc --project tsconfig.types.json",
-		"bundle": "NODE_ENV=${NODE_ENV:-development}; vite build --config vite.config.ts --mode $NODE_ENV"
+		"bundle": "NODE_ENV=${NODE_ENV:-development}; vite build --config vite.config.ts --mode $NODE_ENV",
+		"test": "NODE_ENV=${NODE_ENV:-test}; npx vitest run --config ./vite.test.config.ts",
+		"test:watch": "NODE_ENV=${NODE_ENV:-test}; npx vitest --config ./vite.test.config.ts",
+		"test:coverage": "NODE_ENV=${NODE_ENV:-test}; npx vitest run --coverage --config ./vite.test.config.ts"
 	},
 	"dependencies": {
-		"@prosopo/api-express-router": "3.1.55",
-		"@prosopo/common": "3.1.49",
-		"@prosopo/logger": "2.0.5",
-		"@prosopo/database": "4.0.1",
-		"@prosopo/dotenv": "3.0.51",
-		"@prosopo/locale": "3.2.9",
-		"@prosopo/provider": "5.0.1",
-		"@prosopo/types": "5.0.1",
-		"@prosopo/types-database": "5.0.1",
+		"@prosopo/api-express-router": "3.1.58",
+		"@prosopo/common": "3.1.50",
+		"@prosopo/logger": "2.0.6",
+		"@prosopo/database": "4.0.4",
+		"@prosopo/dotenv": "3.0.52",
+		"@prosopo/locale": "3.3.0",
+		"@prosopo/provider": "5.0.4",
+		"@prosopo/types": "5.0.3",
+		"@prosopo/types-database": "5.0.3",
 		"cors": "2.8.5",
 		"express": "4.21.2",
+		"express-rate-limit": "7.4.0",
 		"mongoose": "8.24.1"
 	},
 	"devDependencies": {
@@ -45,6 +52,7 @@
 		"@vitest/coverage-v8": "4.1.10",
 		"concurrently": "9.0.1",
 		"del-cli": "6.0.0",
+		"dotenv": "16.4.7",
 		"npm-run-all": "4.1.5",
 		"tslib": "2.7.0",
 		"tsx": "4.20.3",

package/src/api.ts

@@ -12,106 +12,197 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+import type { IncomingHttpHeaders } from "node:http";
 import { ProsopoApiError } from "@prosopo/common";
-import { getLogger } from "@prosopo/logger";
+import { type Logger, getLogger } from "@prosopo/logger";
 import { getJA4 } from "@prosopo/provider";
 import {
 	ClientApiPaths,
+	type ProcaptchaOutput,
+	type ProcaptchaToken,
 	VerifySolutionBody,
 	decodeProcaptchaOutput,
 } from "@prosopo/types";
 import type { VerifySolutionBodyTypeOutput } from "@prosopo/types";
-import express, { type Router } from "express";
-import { JA4Database } from "./db.js";
+import express, { type RequestHandler, type Router } from "express";
+import { rateLimit } from "express-rate-limit";
+import { JA4Database, type JA4Store } from "./db.js";
+import { verifyProcaptchaOutput } from "./verify.js";
+
+/** Just enough of an express request for the handlers below. */
+export interface ApiRequest {
+	body: unknown;
+	headers: IncomingHttpHeaders;
+	t: (key: string) => string;
+}
+
+/** Just enough of an express response for the handlers below. */
+export interface ApiResponse {
+	json: (body: object) => unknown;
+	status: (code: number) => { send: (body: string) => unknown };
+}
+
+export type ApiNext = (error: unknown) => void;
+
+export interface RouterDeps {
+	db: JA4Store;
+	getJA4: (
+		headers: IncomingHttpHeaders,
+		logger?: Logger,
+	) => Promise<{ ja4PlusFingerprint: string }>;
+	decodeToken: (token: ProcaptchaToken) => ProcaptchaOutput;
+	logger: Logger;
+}
+
+export const DEFAULT_MONGO_URL = "mongodb://localhost:27017";
+export const DEFAULT_MONGO_DBNAME = "client";
+export const DEFAULT_MONGO_AUTH_SOURCE = "admin";
+
+export const createDatabase = (
+	env: NodeJS.ProcessEnv = process.env,
+): JA4Database =>
+	new JA4Database(
+		env.MONGO_URL || DEFAULT_MONGO_URL,
+		env.MONGO_DBNAME || DEFAULT_MONGO_DBNAME,
+		env.MONGO_AUTH_SOURCE || DEFAULT_MONGO_AUTH_SOURCE,
+	);
+
+export const defaultRouterDeps = (): RouterDeps => ({
+	db: createDatabase(),
+	getJA4,
+	decodeToken: decodeProcaptchaOutput,
+	logger: getLogger("info", "provider-mock:api"),
+});
 
 /**
- * Returns a router connected to the database which can interact with the Proposo protocol
+ * Verify a solution, as the real provider would.
  *
- * @return {Router} - A middleware router that can interact with the Prosopo protocol
+ * A body that does not parse is the caller's fault and is reported as a 400; a
+ * token that parses but cannot be decoded is reported as a 500, because at that
+ * point the request looked well formed and the mock cannot tell the difference
+ * between a corrupt token and a bug of its own.
  */
-export function prosopoRouter(): Router {
-	const router = express.Router();
-	const db = new JA4Database(
-		process.env.MONGO_URL || "mongodb://localhost:27017",
-		process.env.MONGO_DBNAME || "client",
-		process.env.MONGO_AUTH_SOURCE || "admin",
-	);
+export const createVerifyHandler =
+	(deps: RouterDeps) =>
+	async (req: ApiRequest, res: ApiResponse, next: ApiNext): Promise<void> => {
+		let body: VerifySolutionBodyTypeOutput;
+		try {
+			body = VerifySolutionBody.parse(req.body);
+		} catch (err) {
+			return next(
+				new ProsopoApiError("CAPTCHA.PARSE_ERROR", {
+					context: { error: err, code: 400 },
+					logLevel: "info",
+				}),
+			);
+		}
+		try {
+			const outcome = verifyProcaptchaOutput(deps.decodeToken(body.token));
+			res.json({
+				status: req.t(outcome.statusMessage),
+				verified: outcome.verified,
+				...(outcome.commitmentId === undefined
+					? {}
+					: { commitmentId: outcome.commitmentId }),
+			});
+		} catch (err) {
+			return next(
+				new ProsopoApiError("API.UNKNOWN", {
+					context: { error: err, code: 500 },
+				}),
+			);
+		}
+	};
 
-	/**
-	 * Verifies a user's solution as being approved or not
-	 *
-	 * @param {string} userAccount - Dapp User id
-	 * @param {string} commitmentId - The captcha solution to look up
-	 */
-	router.post(
-		ClientApiPaths.VerifyImageCaptchaSolutionDapp,
-		async (req, res, next) => {
-			let body: VerifySolutionBodyTypeOutput;
-			try {
-				body = VerifySolutionBody.parse(req.body);
-			} catch (err) {
-				return next(
-					new ProsopoApiError("CAPTCHA.PARSE_ERROR", {
-						context: { error: err, code: 400 },
-						logLevel: "info",
-					}),
-				);
-			}
+/** Record the caller's JA4 fingerprint and hand it back to them. */
+export const createTestHandler =
+	(deps: RouterDeps) =>
+	async (req: ApiRequest, res: ApiResponse): Promise<void> => {
+		try {
+			const { ja4PlusFingerprint } = await deps.getJA4(
+				req.headers,
+				deps.logger,
+			);
 			try {
-				const { token } = body;
-				const { user, dapp, commitmentId } = decodeProcaptchaOutput(token);
-				const testCommitmentId = "0x123456789test";
-				const testAccount = "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY";
-				const testDapp = "5C4hrfjw9DjXZTzV3MwzrrAr9P1MJhSrvWGWqi1eSuyUpnhM";
-				let statusMessage = "API.USER_NOT_VERIFIED";
-				let approved = false;
-				if (
-					(user && user === testAccount) ||
-					(commitmentId && commitmentId === testCommitmentId) ||
-					(dapp && dapp === testDapp)
-				) {
-					approved = true;
-					statusMessage = "API.USER_VERIFIED";
-					return res.json({
-						status: req.t(statusMessage),
-						verified: approved,
-						commitmentId: testCommitmentId,
-					});
-				}
-
-				return res.json({
-					status: req.t(statusMessage),
-					verified: false,
+				await deps.db.connect();
+				await deps.db.addOrUpdateJA4Record({
+					ja4_fingerprint: ja4PlusFingerprint,
+					user_agent_string: req.headers["user-agent"] || "",
 				});
-			} catch (err) {
-				return next(
-					new ProsopoApiError("API.UNKNOWN", {
-						context: { error: err, code: 500 },
-					}),
-				);
+			} finally {
+				// The close used to be skipped whenever anything above it threw, so
+				// every failing request leaked its connection.
+				await deps.db.close();
 			}
-		},
-	);
-
-	router.get("/test", async (req, res) => {
-		try {
-			const logger = getLogger("info", "provider-mock:api:test");
-			const ja4PlusFingerprint = await getJA4(req.headers, logger);
-			await db.connect();
-			await db.addOrUpdateJA4Record({
-				ja4_fingerprint: ja4PlusFingerprint.ja4PlusFingerprint,
-				user_agent_string: req.headers["user-agent"] || "",
-			});
-			await db.close();
-			return res.json({
-				ja4: ja4PlusFingerprint.ja4PlusFingerprint,
+			res.json({
+				ja4: ja4PlusFingerprint,
 				ua: req.headers["user-agent"],
 			});
 		} catch (e) {
-			console.error("Error parsing ClientHello:", e);
-			return res.status(500).send("Error parsing ClientHello.");
+			// The block above fingerprints and then writes to mongo, so naming
+			// ClientHello here reported a database outage as a parse failure.
+			deps.logger.error(() => ({
+				err: e instanceof Error ? e : new Error(String(e)),
+				msg: "Failed to record the caller's JA4 fingerprint",
+			}));
+			res.status(500).send("Failed to record the caller's JA4 fingerprint.");
 		}
+	};
+
+/**
+ * Both routes do unauthenticated work on the caller's behalf — one verifies a
+ * token, the other writes a fingerprint to mongo — so an unthrottled client can
+ * drive the database as fast as it can send. The window is generous enough that
+ * the demos and cypress runs never see it.
+ */
+export const verifyRateLimit = (): RequestHandler =>
+	rateLimit({
+		windowMs: 60_000,
+		limit: 600,
+		standardHeaders: true,
+		legacyHeaders: false,
 	});
 
+/**
+ * Adapt a handler written against the narrow request/response types above to
+ * the express signature. Express hands the same objects through untouched; the
+ * narrow types exist only so tests can pass plain objects.
+ */
+export const toRequestHandler = (
+	handler: (req: ApiRequest, res: ApiResponse, next: ApiNext) => Promise<void>,
+): RequestHandler => {
+	const adapted: RequestHandler = (req, res, next): void => {
+		// Express ignores a returned promise, so a rejection here would surface as
+		// an unhandled rejection and the request would hang; hand it to the error
+		// middleware instead.
+		handler(
+			req as unknown as ApiRequest,
+			res as unknown as ApiResponse,
+			next,
+		).catch(next);
+	};
+	return adapted;
+};
+
+/**
+ * Returns a router connected to the database which can interact with the Proposo protocol
+ *
+ * @return {Router} - A middleware router that can interact with the Prosopo protocol
+ */
+export function prosopoRouter(deps: RouterDeps = defaultRouterDeps()): Router {
+	const router = express.Router();
+
+	router.post(
+		ClientApiPaths.VerifyImageCaptchaSolutionDapp,
+		verifyRateLimit(),
+		toRequestHandler(createVerifyHandler(deps)),
+	);
+
+	router.get(
+		"/test",
+		verifyRateLimit(),
+		toRequestHandler(createTestHandler(deps)),
+	);
+
 	return router;
 }

package/src/db.ts

@@ -19,11 +19,11 @@ import type { Tables } from "@prosopo/types-database";
 import type mongoose from "mongoose";
 import { Schema } from "mongoose";
 
-enum TableNames {
+export enum TableNames {
 	ja4 = "ja4",
 }
 
-type JA4Data = {
+export type JA4Data = {
 	application?: string;
 	library?: string;
 	device?: string;
@@ -43,7 +43,19 @@ type JA4Data = {
 	ja4tscan_fingerprint?: string;
 };
 
-type JA4Record = JA4Data & mongoose.Document;
+export type JA4Record = JA4Data & mongoose.Document;
+
+/**
+ * The slice of the database the API depends on.
+ *
+ * Narrower than JA4Database so a caller — a test, or a different storage
+ * backend — can supply one without a mongo connection.
+ */
+export interface JA4Store {
+	connect: () => Promise<void>;
+	close: () => Promise<void>;
+	addOrUpdateJA4Record: (record: JA4Data) => Promise<JA4Record | null>;
+}
 
 const JA4Schema = new Schema({
 	application: String,
@@ -90,15 +102,30 @@ export class JA4Database extends MongoDatabase {
 
 	override async connect(): Promise<void> {
 		await super.connect();
-		DATA_TABLES.map(({ collectionName, modelName, schema }) => {
-			if (this.connection) {
-				this.tables[collectionName] = this.connection.model(modelName, schema);
-			}
-		});
+		const connection = this.connection;
+		if (connection === undefined) {
+			// super.connect() resolves only once the connection is open, so this
+			// cannot normally happen — but the models below would be read off
+			// undefined if it ever did, which is a worse error to debug.
+			throw new ProsopoDBError("DATABASE.CONNECTION_UNDEFINED", {
+				context: { failedFuncName: this.connect.name },
+				logger: this.logger,
+			});
+		}
+		for (const { collectionName, modelName, schema } of DATA_TABLES) {
+			this.tables[collectionName] = connection.model(modelName, schema);
+		}
 	}
 
+	/**
+	 * The registered models.
+	 *
+	 * The check used to be `!this.tables`, which the constructor makes
+	 * impossible, so querying before connect() failed with a TypeError on
+	 * undefined rather than the database error it is.
+	 */
 	getTables(): Tables<TableNames> {
-		if (!this.tables) {
+		if (this.tables[TableNames.ja4] === undefined) {
 			throw new ProsopoDBError("DATABASE.TABLES_UNDEFINED", {
 				context: { failedFuncName: this.getTables.name },
 				logger: this.logger,
@@ -108,14 +135,14 @@ export class JA4Database extends MongoDatabase {
 	}
 
 	async getJA4Records(): Promise<JA4Record[]> {
-		return this.tables.ja4.find<JA4Record>({});
+		return this.getTables().ja4.find<JA4Record>({});
 	}
 
 	async getJA4RecordByFingerprintAndUserAgent(
 		ja4Fingerprint: string,
 		userAgentString: string,
 	): Promise<JA4Record | null> {
-		return this.tables.ja4.findOne<JA4Record>({
+		return this.getTables().ja4.findOne<JA4Record>({
 			ja4_fingerprint: ja4Fingerprint,
 			user_agent_string: userAgentString,
 		});
@@ -134,7 +161,7 @@ export class JA4Database extends MongoDatabase {
 			await existingRecord.save();
 			return existingRecord;
 		}
-		const newRecord = new this.tables.ja4(ja4Record);
+		const newRecord = new (this.getTables().ja4)(ja4Record);
 		await newRecord.save();
 		return newRecord;
 	}

package/src/index.ts

@@ -0,0 +1,18 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+export * from "./api.js";
+export * from "./db.js";
+export * from "./isMain.js";
+export * from "./verify.js";

package/src/isMain.ts

@@ -0,0 +1,37 @@
+// Copyright 2021-2026 Prosopo (UK) Ltd.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import { resolve } from "node:path";
+import { argv } from "node:process";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Whether the module at moduleUrl is the one node was asked to run.
+ *
+ * Guards the module's side effects so importing it — for its exports, or from a
+ * test — does not start a server.
+ */
+export const isMain = (
+	moduleUrl: string,
+	entrypoint: string | undefined = argv[1],
+): boolean => {
+	if (entrypoint === undefined) {
+		return false;
+	}
+	// argv[1] is whatever was typed, so `node ./dist/start.js` gives a relative
+	// path while the module url is always absolute. Resolve before comparing or
+	// the guard is false for every relative entrypoint and the server never
+	// starts.
+	return fileURLToPath(moduleUrl) === resolve(entrypoint);
+};

package/src/start.ts

@@ -14,30 +14,104 @@
 
 import { handleErrors } from "@prosopo/api-express-router";
 import { i18nMiddleware } from "@prosopo/locale";
-import { LogLevel, getLogger } from "@prosopo/logger";
+import { LogLevel, type Logger, getLogger } from "@prosopo/logger";
 import cors from "cors";
-import express from "express";
-import { prosopoRouter } from "./api.js";
-const logger = getLogger(LogLevel.enum.info, "prosopo:provider-mock:start.ts");
+import express, { type Express, type RequestHandler } from "express";
+import { type RouterDeps, prosopoRouter } from "./api.js";
+import { isMain } from "./isMain.js";
 
-async function startApi() {
-	const apiApp = express();
-	const apiPort = "9229";
+export const DEFAULT_API_PORT = 9229;
+
+type Router = ReturnType<typeof prosopoRouter>;
+
+export interface StartDeps {
+	createApp: () => Express;
+	i18n: () => Promise<RequestHandler>;
+	router: (deps?: RouterDeps) => Router;
+	logger: Logger;
+	port: number;
+	exit: (code: number) => void;
+}
+
+export const defaultStartDeps = (
+	env: NodeJS.ProcessEnv = process.env,
+): StartDeps => ({
+	createApp: express,
+	i18n: () => i18nMiddleware({}),
+	router: prosopoRouter,
+	logger: getLogger(LogLevel.enum.info, "prosopo:provider-mock:start.ts"),
+	port: readPort(env),
+	exit: (code: number): void => {
+		process.exit(code);
+	},
+});
+
+/**
+ * The port to listen on.
+ *
+ * The port used to be the string "9229" with no way to change it, so the mock
+ * could not be run twice on one machine. A value that is not a usable port is
+ * ignored rather than passed to listen, where it would either throw or — for a
+ * number out of range — bind somewhere unexpected.
+ */
+export const readPort = (env: NodeJS.ProcessEnv): number => {
+	const raw = env.PROVIDER_MOCK_PORT;
+	if (raw === undefined || raw.trim() === "") {
+		return DEFAULT_API_PORT;
+	}
+	const port = Number(raw);
+	if (!Number.isInteger(port) || port < 0 || port > 65535) {
+		return DEFAULT_API_PORT;
+	}
+	return port;
+};
+
+export const startApi = async (
+	deps: StartDeps = defaultStartDeps(),
+): Promise<Express> => {
+	const apiApp = deps.createApp();
 
 	apiApp.use(cors());
 	apiApp.use(express.json());
-	apiApp.use(await i18nMiddleware({}));
-	apiApp.use(prosopoRouter());
+	apiApp.use(await deps.i18n());
+	apiApp.use(deps.router());
 	apiApp.use(handleErrors);
 
-	apiApp.listen(apiPort, () => {
-		logger.info(() => ({
-			msg: `Prosopo app listening at http://localhost:${apiPort}`,
-		}));
+	// listen() reports a failed bind (EADDRINUSE and friends) on the server's
+	// error event, not by throwing, so returning straight after calling it left
+	// main()'s try/catch with nothing to catch. Settle on whichever event fires
+	// first instead.
+	const server = apiApp.listen(deps.port);
+	await new Promise<void>((resolvePromise, rejectPromise) => {
+		server.once("listening", () => {
+			server.removeListener("error", rejectPromise);
+			deps.logger.info(() => ({
+				msg: `Prosopo app listening at http://localhost:${deps.port}`,
+			}));
+			resolvePromise();
+		});
+		server.once("error", rejectPromise);
 	});
-}
 
-startApi().catch((error) => {
-	logger.error(() => ({ err: error, msg: "Failed to start API" }));
-	process.exit(1);
-});
+	return apiApp;
+};
+
+export const main = async (
+	deps: StartDeps = defaultStartDeps(),
+): Promise<void> => {
+	try {
+		await startApi(deps);
+	} catch (error) {
+		deps.logger.error(() => ({
+			err: error instanceof Error ? error : new Error(String(error)),
+			msg: "Failed to start API",
+		}));
+		deps.exit(1);
+	}
+};
+
+if (isMain(import.meta.url)) {
+	// Not awaited: a top-level await cannot be emitted in the cjs build, and
+	// main() already handles its own failures rather than rejecting.
+	void main();
+}