@prosopo/client-example-server 2.7.56 → 2.7.90

package/env.test

@@ -0,0 +1,10 @@
+PROSOPO_VERIFY_ENDPOINT=https://localhost:9235/test/siteverify
+PROSOPO_VERIFICATION_TYPE=api
+PROSOPO_SITE_KEY=5GCP69mhanZqJqnTvaaGvJCJZWSahz6xE2c7bTGETqSB5KDK
+PROSOPO_WEB2=true
+PROSOPO_SERVER_URL=https://localhost
+PROSOPO_SITE_PRIVATE_KEY=bottom drive obey lake curtain smoke basket hold race lonely fit walk
+PROSOPO_SERVER_PORT=9228
+PROSOPO_DEFAULT_ENVIRONMENT=test
+PROSOPO_MONGO_EVENTS_URI=mongodb+srv://<MONGO_URI_HERE>/frictionless_events
+_DEV_ONLY_WATCH_EVENTS=false

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@prosopo/client-example-server",
-	"version": "2.7.56",
+	"version": "2.7.90",
 	"description": "Backend for client-example",
 	"main": "dist/app.js",
 	"types": "dist/app.d.ts",
@@ -18,7 +18,7 @@
 	},
 	"scripts": {
 		"dev": "NODE_ENV=${NODE_ENV:-development}; vite serve --mode=$NODE_ENV --config ./vite.config.ts --host",
-		"start": "node ./dist/app.js",
+		"start": "NODE_ENV=${NODE_ENV:-development}; node ./dist/app.js",
 		"start:bundle": "node ./dist/bundle/prosopo_client_example_server.app.bundle.js",
 		"build": "npm run build:cross-env -- --mode ${NODE_ENV:-development}",
 		"build:cross-env": "vite build --config vite.esm.config.ts",
@@ -29,7 +29,8 @@
 	},
 	"repository": {
 		"type": "git",
-		"url": "git+https://github.com/prosopo/client-example-server.git"
+		"url": "git+https://github.com/prosopo/captcha.git",
+		"directory": "demos/client-example-server"
 	},
 	"author": "PROSOPO LIMITED <info@prosopo.io>",
 	"license": "Apache-2.0",
@@ -41,12 +42,13 @@
 		"@noble/hashes": "1.8.0",
 		"@polkadot/util": "13.5.7",
 		"@polkadot/util-crypto": "13.5.7",
-		"@prosopo/common": "3.1.28",
-		"@prosopo/dotenv": "3.0.33",
-		"@prosopo/keyring": "2.9.0",
-		"@prosopo/server": "2.9.52",
-		"@prosopo/types": "3.8.0",
-		"@prosopo/util": "3.2.5",
+		"@prosopo/common": "3.1.38",
+		"@prosopo/logger": "1.0.2",
+		"@prosopo/dotenv": "3.0.43",
+		"@prosopo/keyring": "2.9.34",
+		"@prosopo/server": "2.10.12",
+		"@prosopo/types": "4.3.0",
+		"@prosopo/util": "3.2.15",
 		"@typegoose/auto-increment": "4.13.0",
 		"cors": "2.8.5",
 		"express": "4.21.2",
@@ -56,7 +58,7 @@
 		"zod": "3.23.8"
 	},
 	"devDependencies": {
-		"@prosopo/config": "3.3.0",
+		"@prosopo/config": "3.3.1",
 		"@types/jsonwebtoken": "9.0.6",
 		"@types/node": "22.10.2",
 		"@vitest/coverage-v8": "3.2.4",

package/src/app.ts

@@ -0,0 +1,169 @@
+// 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 fs from "node:fs";
+import http from "node:http";
+import https from "node:https";
+import type { ServerOptions } from "node:https";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { ProsopoEnvError } from "@prosopo/common";
+import { loadEnv } from "@prosopo/dotenv";
+import { getLogger } from "@prosopo/logger";
+import { getServerConfig } from "@prosopo/server";
+import { at } from "@prosopo/util";
+import cors from "cors";
+import express from "express";
+import routesFactory from "./routes/routes.js";
+import connectionFactory from "./utils/connection.js";
+import memoryServerSetup from "./utils/database.js";
+
+loadEnv();
+
+enum ProsopoVerificationType {
+	api = "api",
+	local = "local",
+}
+
+const logger = getLogger("info", import.meta.url);
+
+async function main() {
+	loadEnv();
+
+	const apiPrefix =
+		process.env.NODE_ENV && process.env.NODE_ENV === "production"
+			? ""
+			: `${process.env.NODE_ENV}-`;
+	const verifyEndpoint =
+		process.env.PROSOPO_VERIFY_ENDPOINT ||
+		`https://${apiPrefix}api.prosopo.io/siteverify`;
+
+	logger.info(() => ({ data: { verifyEndpoint } }));
+
+	const verifyType: ProsopoVerificationType = Object.keys(
+		ProsopoVerificationType,
+	).includes(process.env.PROSOPO_VERIFICATION_TYPE as string)
+		? (process.env.PROSOPO_VERIFICATION_TYPE as ProsopoVerificationType)
+		: ProsopoVerificationType.api;
+
+	const app = express();
+
+	// https://express-rate-limit.mintlify.app/guides/troubleshooting-proxy-issues
+	app.set("trust proxy", 1);
+
+	app.use(cors({ origin: true, credentials: true }));
+
+	app.use(express.urlencoded({ extended: true }));
+
+	app.use(express.json());
+
+	app.use((_, res, next) => {
+		res.setHeader("Access-Control-Allow-Origin", "*");
+		res.setHeader(
+			"Access-Control-Allow-Methods",
+			"GET, POST, PUT, PATCH, DELETE",
+		);
+		res.setHeader(
+			"Access-Control-Allow-Headers",
+			"Origin, Content-Type, X-Auth-Token, Authorization",
+		);
+		next();
+	});
+
+	app.options("/*", (_, res) => {
+		res.sendStatus(200);
+	});
+
+	if (
+		!process.env.MONGO_URI &&
+		process.env.NODE_ENV !== "development" &&
+		process.env.NODE_ENV !== "test"
+	) {
+		throw new Error(
+			"Cannot run mongo memory when NODE_ENV is neither development nor test",
+		);
+	}
+	logger.info(() => ({ msg: process.env.MONGO_URI }));
+	const uri = process.env.MONGO_URI || (await memoryServerSetup());
+	logger.info(() => ({ msg: "mongo uri", data: { uri } }));
+	const mongoose = connectionFactory(uri);
+	if (!process.env.PROSOPO_SITE_PRIVATE_KEY) {
+		const mnemonicError = new ProsopoEnvError("GENERAL.MNEMONIC_UNDEFINED", {
+			context: { missingParams: ["PROSOPO_SITE_PRIVATE_KEY"] },
+			logger,
+		});
+
+		logger.error(() => ({ err: mnemonicError }));
+	}
+
+	const config = getServerConfig();
+
+	logger.info(() => ({ msg: "Config", data: { config } }));
+
+	app.use(routesFactory(mongoose, config, verifyEndpoint, verifyType));
+
+	const port = config.serverUrl
+		? Number.parseInt(at(config.serverUrl.split(":"), 2))
+		: 9228;
+
+	logger.info(() => ({ msg: "Listening on port", data: { port } }));
+
+	// Use HTTPS only in development/test when we have certificates
+	// In production, use HTTP because Caddy handles TLS termination
+	const isDev =
+		process.env.NODE_ENV === "development" || process.env.NODE_ENV === "test";
+
+	if (isDev) {
+		const __filename = fileURLToPath(import.meta.url);
+		const __dirname = path.dirname(__filename);
+		const certsDir = path.resolve(__dirname, "../../../certs");
+
+		const keyPath = path.join(certsDir, "server.key");
+		const certPath = path.join(certsDir, "server.crt");
+
+		if (fs.existsSync(keyPath) && fs.existsSync(certPath)) {
+			const httpsOptions: ServerOptions = {
+				key: fs.readFileSync(keyPath),
+				cert: fs.readFileSync(certPath),
+			};
+
+			https.createServer(httpsOptions, app).listen(port, () => {
+				logger.info(() => ({ msg: `HTTPS server started on port ${port}` }));
+			});
+		} else {
+			logger.warn(() => ({
+				msg: "Certificates not found, starting HTTP server instead. Run ./setup_certs.sh to enable HTTPS in development.",
+			}));
+			http.createServer(app).listen(port, () => {
+				logger.info(() => ({ msg: `HTTP server started on port ${port}` }));
+			});
+		}
+	} else {
+		// Production: use plain HTTP, Caddy handles TLS
+		http.createServer(app).listen(port, () => {
+			logger.info(() => ({
+				msg: `HTTP server started on port ${port} (TLS handled by reverse proxy)`,
+			}));
+		});
+	}
+}
+
+main()
+	.then(() => {
+		logger.info(() => ({ msg: "Server started" }));
+	})
+	.catch((err) => {
+		logger.error(() => ({ err }));
+		process.exit();
+	});

package/src/controllers/auth.ts

@@ -0,0 +1,371 @@
+// 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 { blake2b } from "@noble/hashes/blake2b";
+import { u8aToHex } from "@polkadot/util";
+import { randomAsHex } from "@polkadot/util-crypto";
+import { ProsopoEnvError } from "@prosopo/common";
+import { getPair } from "@prosopo/keyring";
+import { getLogger } from "@prosopo/logger";
+import { ProsopoServer } from "@prosopo/server";
+import {
+	ApiParams,
+	CaptchaType,
+	type KeyringPair,
+	ProcaptchaResponse,
+	type ProcaptchaToken,
+	type ProsopoServerConfigOutput,
+} from "@prosopo/types";
+import { at } from "@prosopo/util";
+import type { NextFunction, Request, Response } from "express";
+import jwt, { type JwtPayload } from "jsonwebtoken";
+import type { Connection } from "mongoose";
+import { z } from "zod";
+import type { UserInterface } from "../models/user.js";
+
+const logger = getLogger("info", import.meta.url);
+
+const SubscribeBodySpec = ProcaptchaResponse.merge(
+	z.object({
+		email: z.string().email(),
+		password: z.string(),
+		siteKey: z.string(),
+	}),
+);
+
+function hashPassword(password: string): string {
+	return u8aToHex(blake2b(password));
+}
+
+const NO_IP = "NO_IP";
+
+/**
+ * Derives the correct KeyringPair and secret for a given site key by trying different captcha types.
+ * @param baseSecret - The base secret from config
+ * @param siteKey - The site key to match against
+ * @returns Object containing the matched pair and its corresponding secret
+ * @throws Error if no matching pair is found
+ */
+const getPairAndSecretForSiteKey = (
+	baseSecret: string,
+	siteKey: string,
+): { pair: KeyringPair; secret: string } => {
+	let pair: KeyringPair | undefined;
+	let secret = baseSecret;
+
+	pair = getPair(secret);
+
+	if (pair.address === siteKey) {
+		logger.info(() => ({
+			msg: "Site key matches the server configuration without captcha type suffix",
+			data: {
+				siteKeyDerived: pair?.address,
+				siteKey,
+			},
+		}));
+		return { pair, secret };
+	}
+
+	for (const captchaType of [
+		CaptchaType.pow,
+		CaptchaType.image,
+		CaptchaType.frictionless,
+		CaptchaType.puzzle,
+	]) {
+		const newSecret = `${baseSecret}//${captchaType}`;
+		pair = getPair(newSecret);
+		console.log(
+			`[PAIR CHECK] Checking pair for ${captchaType}: ${pair?.address} (expected: ${siteKey})`,
+		);
+		logger.info(() => ({
+			msg: "Checking pair",
+			data: {
+				captchaType,
+				siteKeyDerived: pair?.address,
+				siteKey,
+			},
+		}));
+		if (pair.address === siteKey) {
+			console.log(`[PAIR CHECK] ✅ Match found for ${captchaType}!`);
+			secret = newSecret;
+			break;
+		}
+	}
+
+	if (!pair || pair.address !== siteKey) {
+		throw new Error(
+			`Site key does not match the server configuration: Provided ${siteKey} vs Server ${pair?.address}`,
+		);
+	}
+
+	return { pair, secret };
+};
+
+const getResponse = async (
+	ip: string,
+	token: ProcaptchaToken,
+	secret: string,
+	verifyEndpoint: string,
+	email?: string,
+) => {
+	// Only include ip if environment is production
+	const body: Record<string, string> = {
+		[ApiParams.token]: token,
+		[ApiParams.secret]: secret,
+		...(email ? { [ApiParams.email]: email } : {}),
+	};
+
+	if (process.env.NODE_ENV !== "development") {
+		body[ApiParams.ip] = ip;
+	}
+
+	logger.info(() => ({
+		data: {
+			body,
+		},
+	}));
+
+	const response = await fetch(verifyEndpoint, {
+		method: "POST",
+		body: JSON.stringify(body),
+	});
+	return response.json();
+};
+
+const verify = async (
+	prosopoServer: ProsopoServer,
+	verifyType: string,
+	verifyEndpoint: string,
+	token: ProcaptchaToken,
+	secret: string,
+	ip: string,
+	email?: string,
+) => {
+	if (verifyType === "api") {
+		// verify using the API endpoint
+		logger.info(() => ({
+			msg: "Verifying using the API endpoint",
+			data: {
+				verifyEndpoint,
+			},
+		}));
+
+		const response = await getResponse(
+			ip,
+			token,
+			secret,
+			verifyEndpoint,
+			email,
+		);
+		logger.info(() => ({
+			data: {
+				response,
+			},
+		}));
+		return response.verified;
+	}
+	// verify using the TypeScript library
+	const verified = await prosopoServer.isVerified(token, ip, email);
+	logger.info(() => ({
+		data: {
+			verified,
+		},
+	}));
+	return verified[ApiParams.verified];
+};
+
+const signup = async (
+	mongoose: Connection,
+	config: ProsopoServerConfigOutput,
+	verifyEndpoint: string,
+	verifyType: string,
+	req: Request,
+	res: Response,
+	next: NextFunction,
+) => {
+	try {
+		if (!config.account.secret) {
+			throw new ProsopoEnvError("GENERAL.MNEMONIC_UNDEFINED", {
+				context: { missingParams: ["PROSOPO_SITE_PRIVATE_KEY"] },
+			});
+		}
+		const User = mongoose.model<UserInterface>("User");
+		// checks if email exists
+		const dbUser = await User.findOne({
+			email: { $eq: req.body.email },
+		});
+		const payload = SubscribeBodySpec.parse(req.body);
+		// get the procaptcha-response token
+		const token = payload[ApiParams.procaptchaResponse];
+		const siteKey = payload[ApiParams.siteKey];
+
+		const { pair, secret } = getPairAndSecretForSiteKey(
+			config.account.secret,
+			siteKey,
+		);
+
+		const prosopoServer = new ProsopoServer(config, pair);
+		if (dbUser) {
+			return res.status(409).json({ message: "email already exists" });
+		}
+
+		const email = req.body.email;
+		const verified = await verify(
+			prosopoServer,
+			verifyType,
+			verifyEndpoint,
+			token,
+			secret,
+			req.headers["x-client-ip"]?.toString() || "127.0.0.1",
+			email,
+		);
+
+		if (verified === true) {
+			// salt
+			const salt = randomAsHex(32);
+			// !!!DUMMY CODE!!! - Do not use in production. Use bcrypt or similar for password hashing.
+			const passwordHash = hashPassword(`${req.body.password}${salt}`);
+			if (passwordHash) {
+				return User.create({
+					email: email,
+					name: req.body.name,
+					password: passwordHash,
+					salt: salt,
+				})
+					.then(() => {
+						res.status(200).json({ message: "user created" });
+					})
+					.catch((err) => {
+						logger.error(() => ({
+							err,
+							msg: "Error creating user in database",
+						}));
+						res.status(502).json({ message: "error while creating the user" });
+					});
+			}
+		} else {
+			res
+				.status(401)
+				.json({ message: "user has not completed a captcha", verified });
+		}
+	} catch (err) {
+		console.error("error", err);
+		res
+			.status(500)
+			.json({ message: (err as Error).message || "internal server error" });
+	}
+};
+
+const login = async (
+	mongoose: Connection,
+	config: ProsopoServerConfigOutput,
+	verifyEndpoint: string,
+	verifyType: string,
+	req: Request,
+	res: Response,
+) => {
+	const User = mongoose.model<UserInterface>("User");
+
+	// checks if email exists
+	await User.findOne({
+		email: { $eq: req.body.email },
+	})
+		.then(async (dbUser) => {
+			if (dbUser) {
+				const payload = SubscribeBodySpec.parse(req.body);
+
+				const token = payload[ApiParams.procaptchaResponse];
+				const siteKey = payload[ApiParams.siteKey];
+
+				if (!config.account.secret) {
+					throw new ProsopoEnvError("GENERAL.SECRET_MISSING", {
+						context: { missingParams: ["PROSOPO_SITE_PRIVATE_KEY"] },
+					});
+				}
+
+				const { pair, secret } = getPairAndSecretForSiteKey(
+					config.account.secret,
+					siteKey,
+				);
+				const prosopoServer = new ProsopoServer(config, pair);
+
+				const verified = await verify(
+					prosopoServer,
+					verifyType,
+					verifyEndpoint,
+					token,
+					secret,
+					req.headers["x-client-ip"]?.toString() || NO_IP,
+				);
+
+				logger.info(() => ({
+					data: {
+						verified,
+					},
+				}));
+
+				if (verified) {
+					// password hash
+					// !!!DUMMY CODE!!! - Do not use in production. Use bcrypt or similar for password hashing.
+					const passwordHash = hashPassword(
+						`${req.body.password}${dbUser.salt}`,
+					);
+					if (passwordHash !== dbUser.password) {
+						// password doesnt match
+						return res.status(401).json({ message: "invalid credentials" });
+					}
+					// password match
+					const token = jwt.sign({ email: req.body.email }, "secret", {
+						expiresIn: "1h",
+					});
+					return res
+						.status(200)
+						.json({ message: "user logged in", token: token });
+				}
+				return res
+					.status(401)
+					.json({ message: "user has not completed a captcha", verified });
+			}
+			return res.status(404).json({ message: "user not found" });
+		})
+		.catch((err) => {
+			console.error("error", err);
+			res.status(500).json({ message: err.message || "internal server error" });
+		});
+};
+
+const isAuth = (req: Request, res: Response) => {
+	const authHeader = req.get("Authorization") || "";
+	if (!authHeader) {
+		res.status(401).json({ message: "not authenticated" });
+	}
+
+	const token = at(authHeader.split(" "), 1);
+	let decodedToken: string | JwtPayload = "";
+	try {
+		decodedToken = jwt.verify(token, "secret");
+	} catch (err) {
+		res.status(500).json({
+			message: (err as Error).message || "could not decode the token",
+		});
+	}
+
+	if (!decodedToken) {
+		res.status(401).json({ message: "unauthorized" });
+	} else {
+		res.status(200).json({ message: "here is your resource" });
+	}
+};
+
+export { signup, login, isAuth };

package/src/models/user.ts

@@ -0,0 +1,45 @@
+// 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 mongoose, { Schema } from "mongoose";
+
+export interface UserInterface {
+	id: number;
+	email: string;
+	name: string;
+	password: string;
+	salt: string;
+}
+
+const UserSchema = new Schema<UserInterface>({
+	email: {
+		type: mongoose.SchemaTypes.String,
+		required: true,
+	},
+	name: {
+		type: mongoose.SchemaTypes.String,
+	},
+	password: {
+		type: mongoose.SchemaTypes.String,
+		required: true,
+	},
+	id: {
+		type: mongoose.SchemaTypes.Number,
+	},
+	salt: {
+		type: mongoose.SchemaTypes.String,
+		required: true,
+	},
+});
+
+export default UserSchema;

package/src/routes/routes.ts

@@ -0,0 +1,54 @@
+import type { ProsopoServerConfigOutput } from "@prosopo/types";
+import express from "express";
+// 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 { Connection } from "mongoose";
+import { isAuth, login, signup } from "../controllers/auth.js";
+
+const router = express.Router();
+
+function getRoutes(
+	mongoose: Connection,
+	config: ProsopoServerConfigOutput,
+	verifyEndpoint: string,
+	verifyType: string,
+): express.Router {
+	router.post(
+		"/login",
+		login.bind(null, mongoose, config, verifyEndpoint, verifyType),
+	);
+
+	router.post(
+		"/signup",
+		signup.bind(null, mongoose, config, verifyEndpoint, verifyType),
+	);
+
+	router.get("/private", isAuth);
+
+	router.get("/public", (req, res) => {
+		res.status(200).json({ message: "here is your public resource" });
+	});
+
+	router.get("/health", (req, res) => {
+		res.status(200).json({ status: "ok" });
+	});
+
+	// will match any other path
+	router.use("/", (req, res) => {
+		res.status(404).json({ error: "page not found" });
+	});
+	return router;
+}
+
+export default getRoutes;