@prosopo/api-express-router 3.2.0 → 3.2.1

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,38 +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/jwtReplayGuard.js";
-export * from "./middlewares/requestLoggerMiddleware.js";

package/src/middlewares/authMiddleware.ts

@@ -1,150 +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, ProsopoBaseError } from "@prosopo/common";
-import { type TranslationKey, isTranslationKey } from "@prosopo/locale";
-import type { ApiJsonError, KeyringPair } from "@prosopo/types";
-import type {
-	JWT,
-	JWTVerifyOptions,
-	JWTVerifyResult,
-} from "@prosopo/util-crypto";
-import type { NextFunction, Request, Response } from "express";
-import type { JwtReplayGuard } from "./jwtReplayGuard.js";
-
-export type AuthMiddlewareOptions = {
-	/** Claim checks (audience, maximum lifetime) applied to every token. */
-	verify?: JWTVerifyOptions;
-	/**
-	 * Makes a token that carries a `jti` single-use. Tokens without `jti` are
-	 * unaffected, so existing issuers keep working until they add one.
-	 */
-	replayGuard?: JwtReplayGuard;
-};
-
-const verifyWith = (
-	key: KeyringPair | undefined,
-	jwt: JWT,
-	options: AuthMiddlewareOptions,
-): JWTVerifyResult | undefined => {
-	if (!key) return undefined;
-	const result = key.jwtVerify(jwt, options.verify);
-	return result.isValid ? result : undefined;
-};
-
-const isReplay = (
-	result: JWTVerifyResult,
-	options: AuthMiddlewareOptions,
-): boolean => {
-	const payload = result.payload;
-	if (!options.replayGuard || !payload || typeof payload.jti !== "string") {
-		return false;
-	}
-	return !options.replayGuard.claim(
-		`${payload.sub}:${payload.jti}`,
-		payload.exp,
-	);
-};
-
-export const authMiddleware = (
-	pair: KeyringPair | undefined,
-	authAccount?: KeyringPair | undefined,
-	options: AuthMiddlewareOptions = {},
-) => {
-	return async (req: Request, res: Response, next: NextFunction) => {
-		try {
-			const jwt = extractJWT(req);
-
-			const verified =
-				verifyWith(authAccount, jwt, options) ?? verifyWith(pair, jwt, options);
-
-			if (verified && !isReplay(verified, options)) {
-				next();
-				return;
-			}
-
-			unauthorized(req, res, "API.UNAUTHORIZED");
-			return;
-		} catch (err) {
-			req.logger.error(() => ({ err, msg: "Auth Middleware Error" }));
-			// The thrown value can carry request context, stack or config, so
-			// only its translation key goes back to the caller.
-			unauthorized(req, res, translationKeyOf(err));
-			return;
-		}
-	};
-};
-
-const translationKeyOf = (err: unknown): TranslationKey =>
-	err instanceof ProsopoBaseError &&
-	err.translationKey !== undefined &&
-	isTranslationKey(err.translationKey)
-		? err.translationKey
-		: "API.UNAUTHORIZED";
-
-const unauthorized = (
-	req: Request,
-	res: Response,
-	key: TranslationKey,
-): void => {
-	const body: { error: ApiJsonError } = {
-		error: {
-			code: 401,
-			key,
-			message: req.i18n ? req.i18n.t(key) : key,
-		},
-	};
-	res.status(401).json(body);
-};
-
-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/jwtReplayGuard.ts

@@ -1,56 +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.
-
-export interface JwtReplayGuard {
-	/**
-	 * Record a token id. Returns false when the id was already recorded and has
-	 * not yet expired, i.e. the token is being replayed.
-	 */
-	claim(id: string, expiresAtSeconds: number): boolean;
-}
-
-/**
- * Per-process set of token ids seen until their expiry. Only tokens signed by
- * an admin key reach it, so the size cap guards against a misbehaving issuer
- * rather than an attacker; when full the oldest entry is dropped.
- */
-export const createMemoryJwtReplayGuard = (
-	maxEntries = 10_000,
-	nowSeconds: () => number = () => Date.now() / 1000,
-): JwtReplayGuard => {
-	const seen = new Map<string, number>();
-
-	const sweep = (now: number): void => {
-		for (const [id, exp] of seen) {
-			if (exp < now) seen.delete(id);
-		}
-	};
-
-	return {
-		claim(id: string, expiresAtSeconds: number): boolean {
-			const now = nowSeconds();
-			const previous = seen.get(id);
-			if (previous !== undefined && previous >= now) return false;
-			if (seen.size >= maxEntries) {
-				sweep(now);
-				if (seen.size >= maxEntries) {
-					const oldest = seen.keys().next();
-					if (!oldest.done) seen.delete(oldest.value);
-				}
-			}
-			seen.set(id, expiresAtSeconds);
-			return true;
-		},
-	};
-};

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,196 +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,
-	type AuthMiddlewareOptions,
-	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"
-			| "createMemoryJwtReplayGuard"
-			| "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, auth account and options", () => {
-		expectTypeOf(authMiddleware).parameters.toEqualTypeOf<
-			[
-				pair: KeyringPair | undefined,
-				authAccount?: KeyringPair | undefined,
-				options?: AuthMiddlewareOptions,
-			]
-		>();
-	});
-
-	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);
-	});
-});