@prosopo/api-express-router 3.1.98 → 3.2.1

package/src/endpointAdapter/apiExpressDefaultEndpointAdapter.ts

@@ -1,92 +0,0 @@
-// 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 type { ApiEndpoint } from "@prosopo/api-route";
-import {
-	ProsopoApiError,
-	ProsopoBaseError,
-	unwrapError,
-} from "@prosopo/common";
-import type { LogLevel } from "@prosopo/logger";
-import { stringifyBigInts } from "@prosopo/util";
-import type { NextFunction, Request, Response } from "express";
-import type { ZodType } from "zod";
-import type { ApiExpressEndpointAdapter } from "./apiExpressEndpointAdapter.js";
-
-class ApiExpressDefaultEndpointAdapter implements ApiExpressEndpointAdapter {
-	public constructor(
-		private readonly logLevel: LogLevel,
-		private readonly errorStatusCode: number,
-	) {}
-
-	public async handleRequest(
-		endpoint: ApiEndpoint<ZodType | undefined>,
-		request: Request,
-		response: Response,
-		next: NextFunction,
-	): Promise<void> {
-		let args: unknown;
-		try {
-			args = endpoint.getRequestArgsSchema()?.parse(request.body);
-		} catch (error) {
-			return next(
-				new ProsopoApiError("API.PARSE_ERROR", {
-					context: { code: 400, error: error },
-				}),
-			);
-		}
-
-		try {
-			const apiEndpointResponse = await endpoint.processRequest(
-				args,
-				request.logger,
-			);
-
-			// otherwise .json() will throw "TypeError: Do not know how to serialize a BigInt" as uses JSON.stringify
-			const responseObject = stringifyBigInts(apiEndpointResponse);
-
-			response.json(responseObject);
-		} catch (error) {
-			request.logger.error(() => ({
-				err: error,
-			}));
-
-			// Errors that already carry an explicit HTTP status code (e.g. a 400
-			// admin auth/validation error) should surface that code with the
-			// standard `{ error: ... }` JSON envelope. Everything else — base
-			// errors without a status code, or non-Prosopo errors — is treated as
-			// an unexpected failure and mapped to this adapter's configured
-			// errorStatusCode. In both cases the envelope is produced by
-			// `unwrapError` so the message/key stay consistent and localised.
-			const responseError =
-				error instanceof ProsopoApiError ||
-				(error instanceof ProsopoBaseError &&
-					typeof error.context?.code === "number")
-					? error
-					: new ProsopoApiError("API.UNKNOWN", {
-							context: { code: this.errorStatusCode },
-							silent: true,
-						});
-
-			const { code, statusMessage, jsonError } = unwrapError(
-				responseError,
-				request.i18n,
-			);
-			response.statusMessage = statusMessage;
-			response.status(code).json({ error: jsonError });
-		}
-	}
-}
-
-export { ApiExpressDefaultEndpointAdapter };

package/src/endpointAdapter/apiExpressEndpointAdapter.ts

@@ -1,28 +0,0 @@
-// 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 type { ApiEndpoint } from "@prosopo/api-route";
-import type { NextFunction, Request, Response } from "express";
-import type { ZodType } from "zod";
-
-interface ApiExpressEndpointAdapter {
-	handleRequest(
-		endpoint: ApiEndpoint<ZodType | undefined>,
-		request: Request,
-		response: Response,
-		next: NextFunction,
-	): Promise<void>;
-}
-
-export type { ApiExpressEndpointAdapter };

package/src/errorHandler.ts

@@ -1,33 +0,0 @@
-// 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.
-
-// We need the unused params to make express recognise this function as an error handler
-
-import { type ProsopoApiError, unwrapError } from "@prosopo/common";
-import type { NextFunction, Request, Response } from "express";
-import type { ZodError } from "zod";
-
-export const handleErrors = (
-	err: ProsopoApiError | SyntaxError | ZodError,
-	request: Request,
-	response: Response,
-	next: NextFunction,
-) => {
-	const { code, statusMessage, jsonError } = unwrapError(err, request.i18n);
-	response.statusMessage = statusMessage;
-	response.set("content-type", "application/json");
-	response.status(code);
-	response.send({ error: jsonError });
-	response.end();
-};

package/src/index.ts

@@ -1,37 +0,0 @@
-// 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 type { LogLevel } from "@prosopo/logger";
-import { ApiExpressRouterFactory } from "./apiExpressRouterFactory.js";
-import { ApiExpressDefaultEndpointAdapter } from "./endpointAdapter/apiExpressDefaultEndpointAdapter.js";
-import type { ApiExpressEndpointAdapter } from "./endpointAdapter/apiExpressEndpointAdapter.js";
-
-const apiExpressRouterFactory = new ApiExpressRouterFactory();
-
-const createApiExpressDefaultEndpointAdapter = (
-	logLevel: LogLevel,
-	errorStatusCode = 500,
-): ApiExpressEndpointAdapter => {
-	return new ApiExpressDefaultEndpointAdapter(logLevel, errorStatusCode);
-};
-
-export {
-	apiExpressRouterFactory,
-	createApiExpressDefaultEndpointAdapter,
-	type ApiExpressEndpointAdapter,
-};
-
-export * from "./errorHandler.js";
-export * from "./middlewares/authMiddleware.js";
-export * from "./middlewares/requestLoggerMiddleware.js";

package/src/middlewares/authMiddleware.ts

@@ -1,93 +0,0 @@
-// 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 { hexToU8a } from "@polkadot/util";
-import { ProsopoApiError, ProsopoEnvError } from "@prosopo/common";
-import type { KeyringPair } from "@prosopo/types";
-import type { JWT } from "@prosopo/util-crypto";
-import type { NextFunction, Request, Response } from "express";
-
-export const authMiddleware = (
-	pair: KeyringPair | undefined,
-	authAccount?: KeyringPair | undefined,
-) => {
-	return async (req: Request, res: Response, next: NextFunction) => {
-		try {
-			const jwt = extractJWT(req);
-
-			let error: ProsopoApiError | undefined;
-
-			if (authAccount?.jwtVerify(jwt).isValid) {
-				next();
-				return;
-			}
-
-			if (pair?.jwtVerify(jwt).isValid) {
-				next();
-				return;
-			}
-
-			res.status(401).json({
-				error: new ProsopoEnvError(error || "API.UNAUTHORIZED", {
-					context: { i18n: req.i18n, code: 401 },
-				}),
-			});
-			return;
-		} catch (err) {
-			req.logger.error(() => ({ err, msg: "Auth Middleware Error" }));
-			res.status(401).json({ error: "Unauthorized", message: err });
-			return;
-		}
-	};
-};
-
-const extractJWT = (req: Request) => {
-	const authHeader = req.headers.Authorization || req.headers.authorization;
-
-	if (!authHeader || typeof authHeader !== "string") {
-		throw new ProsopoApiError("GENERAL.MISSING_AUTH_HEADER", {
-			context: { error: "Missing Authorization header", code: 401 },
-		});
-	}
-
-	const jwt = authHeader.replace("Bearer ", "");
-
-	if (!jwt) {
-		throw new ProsopoApiError("GENERAL.INVALID_JWT", {
-			context: { error: "Missing JWT", code: 400 },
-		});
-	}
-
-	return jwt as JWT;
-};
-
-export const verifySignature = (
-	signature: string,
-	message: string,
-	pair: KeyringPair,
-) => {
-	const u8Sig = hexToU8a(signature);
-
-	if (!pair.verify(message, u8Sig, pair.publicKey)) {
-		throw new ProsopoApiError("GENERAL.INVALID_SIGNATURE", {
-			context: {
-				error: "Signature verification failed",
-				code: 401,
-				account: pair.address,
-				message,
-				signature,
-			},
-		});
-	}
-};

package/src/middlewares/requestLoggerMiddleware.ts

@@ -1,104 +0,0 @@
-// 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 type { ProviderEnvironment } from "@prosopo/env";
-import { getLogger, parseLogLevel } from "@prosopo/logger";
-import type { NextFunction, Request, Response } from "express";
-import { v4 as uuidv4 } from "uuid";
-
-const getHeaderValue = (
-	req: Request,
-	headerName: string,
-): string | undefined => {
-	if (headerName in req.headers && req.headers[headerName]) {
-		return req.headers[headerName].toString();
-	}
-	return undefined;
-};
-
-const HEALTH_CHECK_PATHS = new Set(["/healthz", "/health", "/readyz"]);
-
-export function requestLoggerMiddleware(env: ProviderEnvironment) {
-	return (req: Request, res: Response, next: NextFunction) => {
-		// Honour an inbound `x-request-id` (Caddy/upstream proxy assigns one and
-		// we want the same value to link Caddy access logs to Node app logs).
-		// Fall back to `e-<uuid>` when the upstream didn't set one.
-		const requestId =
-			(req.headers["x-request-id"] as string) || `e-${uuidv4()}`;
-		const user = getHeaderValue(req, "prosopo-user");
-		const siteKey = getHeaderValue(req, "prosopo-site-key");
-		const sessionId = req.body?.sessionId ? req.body.sessionId : undefined;
-
-		const logger = getLogger(
-			parseLogLevel(env.config.logLevel),
-			"provider:request",
-		).with({
-			requestId,
-			...(user ? { user } : {}),
-			...(siteKey ? { siteKey } : {}),
-			...(sessionId ? { sessionId } : {}),
-		});
-
-		req.logger = logger;
-		req.requestId = requestId;
-
-		// Mirror the requestId back to the client so downstream systems can
-		// correlate their own logs to ours.
-		res.setHeader("x-request-id", requestId);
-
-		// Skip request/response envelope logging for high-volume health probes
-		// so they don't drown out useful captcha-endpoint entries.
-		if (HEALTH_CHECK_PATHS.has(req.path)) {
-			next();
-			return;
-		}
-
-		// Emit a single request-received line so every endpoint has an entry
-		// log in OpenObserve even when the handler itself doesn't log. Kept at
-		// info level; drop to debug if the volume becomes a problem.
-		const startNs = process.hrtime.bigint();
-		logger.info(() => ({
-			msg: "Request received",
-			data: {
-				method: req.method,
-				path: req.path,
-			},
-		}));
-
-		// Log a response-finished line. `finish` fires when the response was
-		// sent successfully; `close` fires when the client disconnects before
-		// the response was fully sent. Guard against both firing (once() would
-		// only cover a single event source).
-		let finished = false;
-		const emitFinish = (outcome: "finish" | "close") => {
-			if (finished) return;
-			finished = true;
-			const durationMs = Number(process.hrtime.bigint() - startNs) / 1e6;
-			logger.info(() => ({
-				msg: "Response sent",
-				data: {
-					method: req.method,
-					path: req.path,
-					status: res.statusCode,
-					durationMs,
-					outcome,
-				},
-			}));
-		};
-		res.on("finish", () => emitFinish("finish"));
-		res.on("close", () => emitFinish("close"));
-
-		next();
-	};
-}

package/src/tests/apiExpressRouter.test-d.ts

@@ -1,190 +0,0 @@
-// 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 type { ApiEndpoint, ApiRoutesProvider } from "@prosopo/api-route";
-import type { LogLevel } from "@prosopo/logger";
-import type { KeyringPair } from "@prosopo/types";
-import type {
-	NextFunction,
-	Request,
-	RequestHandler,
-	Response,
-	Router,
-} from "express";
-import { assertType, describe, expectTypeOf, test } from "vitest";
-import type { ZodType } from "zod";
-import type * as barrel from "../index.js";
-import {
-	type ApiExpressEndpointAdapter,
-	apiExpressRouterFactory,
-	authMiddleware,
-	createApiExpressDefaultEndpointAdapter,
-	handleErrors,
-	requestLoggerMiddleware,
-	verifySignature,
-} from "../index.js";
-
-/**
- * These pin the package's public type surface. Consumers wire routers and
- * middleware from this barrel alone, so a widened parameter or a dropped export
- * is a break they would only find at their own call sites.
- */
-
-describe("the barrel's shape", () => {
-	test("exports exactly the intended names", () => {
-		expectTypeOf<keyof typeof barrel>().toEqualTypeOf<
-			| "apiExpressRouterFactory"
-			| "createApiExpressDefaultEndpointAdapter"
-			| "handleErrors"
-			| "authMiddleware"
-			| "verifySignature"
-			| "requestLoggerMiddleware"
-		>();
-	});
-});
-
-describe("createApiExpressDefaultEndpointAdapter", () => {
-	test("takes a log level and an optional status code", () => {
-		expectTypeOf(
-			createApiExpressDefaultEndpointAdapter,
-		).parameters.toEqualTypeOf<
-			[logLevel: LogLevel, errorStatusCode?: number]
-		>();
-	});
-
-	test("returns the interface, not the concrete class", () => {
-		// Callers depend on the interface so an alternative adapter can be
-		// substituted without a cast.
-		expectTypeOf(
-			createApiExpressDefaultEndpointAdapter,
-		).returns.toEqualTypeOf<ApiExpressEndpointAdapter>();
-	});
-
-	test("rejects a log level that is not one of the known levels", () => {
-		// @ts-expect-error - an arbitrary string is not a LogLevel
-		createApiExpressDefaultEndpointAdapter("chatty");
-	});
-
-	test("rejects a non-numeric status code", () => {
-		// @ts-expect-error - the status code is a number
-		createApiExpressDefaultEndpointAdapter("info", "500");
-	});
-});
-
-describe("the router factory", () => {
-	test("takes a routes provider and an adapter, and returns a Router", () => {
-		expectTypeOf(apiExpressRouterFactory.createRouter).toEqualTypeOf<
-			(
-				apiRoutesProvider: ApiRoutesProvider,
-				apiExpressEndpointAdapter: ApiExpressEndpointAdapter,
-			) => Router
-		>();
-	});
-
-	test("rejects a bare routes object in place of a provider", () => {
-		const adapter: ApiExpressEndpointAdapter = {
-			handleRequest: async () => undefined,
-		};
-		// @ts-expect-error - the factory wants a provider, not the routes it returns
-		apiExpressRouterFactory.createRouter({}, adapter);
-	});
-});
-
-describe("the endpoint adapter interface", () => {
-	test("takes the endpoint and the express trio and resolves to void", () => {
-		expectTypeOf<ApiExpressEndpointAdapter["handleRequest"]>().toEqualTypeOf<
-			(
-				endpoint: ApiEndpoint<ZodType | undefined>,
-				request: Request,
-				response: Response,
-				next: NextFunction,
-			) => Promise<void>
-		>();
-	});
-
-	test("is satisfied by any object with a matching handleRequest", () => {
-		// Structural, deliberately: a consumer can supply its own adapter
-		// without importing or extending the default class.
-		assertType<ApiExpressEndpointAdapter>({
-			handleRequest: async (): Promise<void> => undefined,
-		});
-	});
-});
-
-describe("the middleware", () => {
-	test("authMiddleware takes an optional pair and an optional auth account", () => {
-		expectTypeOf(authMiddleware).parameters.toEqualTypeOf<
-			[pair: KeyringPair | undefined, authAccount?: KeyringPair | undefined]
-		>();
-	});
-
-	test("authMiddleware returns an async express handler", () => {
-		expectTypeOf(authMiddleware).returns.toEqualTypeOf<
-			(req: Request, res: Response, next: NextFunction) => Promise<void>
-		>();
-	});
-
-	test("authMiddleware still requires the first argument to be passed", () => {
-		// It is `KeyringPair | undefined` rather than optional, so a provider
-		// with no key has to say so explicitly instead of forgetting to wire it.
-		// @ts-expect-error - the first parameter is required
-		authMiddleware();
-	});
-
-	test("requestLoggerMiddleware returns a synchronous express handler", () => {
-		expectTypeOf(requestLoggerMiddleware).returns.toEqualTypeOf<
-			(req: Request, res: Response, next: NextFunction) => void
-		>();
-	});
-
-	test("the handler each factory builds is usable as express middleware", () => {
-		// The exports are factories, so it is what they return — not the
-		// factories themselves — that gets mounted with app.use().
-		assertType<RequestHandler>(
-			requestLoggerMiddleware(
-				{} as Parameters<typeof requestLoggerMiddleware>[0],
-			),
-		);
-		assertType<RequestHandler>(authMiddleware(undefined));
-	});
-
-	test("verifySignature takes a signature, a message and a pair, and returns void", () => {
-		expectTypeOf(verifySignature).parameters.toEqualTypeOf<
-			[signature: string, message: string, pair: KeyringPair]
-		>();
-		expectTypeOf(verifySignature).returns.toEqualTypeOf<void>();
-	});
-
-	test("verifySignature rejects a byte-array signature", () => {
-		// The hex string is decoded internally; passing bytes would be decoded
-		// a second time and silently verify the wrong value.
-		// @ts-expect-error - the signature is a hex string
-		verifySignature(new Uint8Array([1]), "msg", {} as KeyringPair);
-	});
-});
-
-describe("the error handler", () => {
-	test("takes an error first, which is what makes express treat it as one", () => {
-		// A three-parameter handler would be mounted as ordinary middleware and
-		// never see an error at all.
-		expectTypeOf(handleErrors).parameters.toMatchTypeOf<
-			[unknown, Request, Response, NextFunction]
-		>();
-	});
-
-	test("rejects being mounted as an ordinary handler", () => {
-		// @ts-expect-error - the first parameter is an error, not a request
-		assertType<RequestHandler>(handleErrors);
-	});
-});