@prosopo/database 4.1.4 → 4.2.1

package/dist/databases/provider.js

@@ -1,7 +1,7 @@
 import { MongoDatabase } from "../base/mongo.js";
 import { ProsopoDBError } from "@prosopo/common";
 import { CaptchaStates, CaptchaStatus, CaptchaType, DatasetWithIdsAndTreeSchema, DecisionMachineKind, StoredStatusNames, UserCommitmentSchema, isBlockingCaptchaResult } from "@prosopo/types";
-import { CaptchaRecordSchema, ClientRecordSchema, DatasetRecordSchema, DecisionMachineArtifactRecordSchema, PoWCaptchaRecordSchema, PuzzleCaptchaRecordSchema, SESSION_PROJECTION, ScheduledTaskRecordSchema, ScheduledTaskSchema, SessionRecordSchema, SolutionRecordSchema, SpamEmailDomainRecordSchema, UserCommitmentRecordSchema, UserSolutionRecordSchema } from "@prosopo/types-database";
+import { AudioCaptchaRecordSchema, CaptchaRecordSchema, ClientRecordSchema, DatasetRecordSchema, DecisionMachineArtifactRecordSchema, IconOrderCaptchaRecordSchema, PoWCaptchaRecordSchema, PuzzleCaptchaRecordSchema, SESSION_PROJECTION, ScheduledTaskRecordSchema, ScheduledTaskSchema, SessionRecordSchema, SolutionRecordSchema, SpamEmailDomainRecordSchema, UserCommitmentRecordSchema, UserSolutionRecordSchema } from "@prosopo/types-database";
 import { isHex } from "@polkadot/util/is";
 import { connectToRedis, setupRedisIndex } from "@prosopo/redis-client";
 import { accessRulesRedisIndex, createRedisAccessRulesStorage } from "@prosopo/user-access-policy/redis";
@@ -23,6 +23,16 @@ var PROVIDER_TABLES = [
 		modelName: "PuzzleCaptcha",
 		schema: PuzzleCaptchaRecordSchema
 	},
+	{
+		collectionName: "audiocaptcha",
+		modelName: "AudioCaptcha",
+		schema: AudioCaptchaRecordSchema
+	},
+	{
+		collectionName: "iconordercaptcha",
+		modelName: "IconOrderCaptcha",
+		schema: IconOrderCaptchaRecordSchema
+	},
 	{
 		collectionName: "dataset",
 		modelName: "Dataset",
@@ -640,46 +650,76 @@ var ProviderDatabase = class ProviderDatabase extends MongoDatabase {
 			$unset: { pendingStage: 1 }
 		}).then(() => {}));
 	}
-	async storePuzzleCaptchaRecord(challenge, components, targetX, targetY, originX, originY, tolerance, providerSignature, ipAddress, headers, ja4, sessionId, ipInfo) {
-		const tables = this.getTables();
-		const puzzleCaptchaRecord = {
+	interactiveCollection(captchaType) {
+		switch (captchaType) {
+			case CaptchaType.puzzle: return {
+				table: "puzzlecaptcha",
+				label: "PuzzleCaptcha",
+				captchaType,
+				answerProjection: {
+					targetX: 1,
+					targetY: 1,
+					originX: 1,
+					originY: 1,
+					tolerance: 1,
+					puzzleEvents: 1
+				},
+				streamRecord: (record, markStored) => this.centralStreamer?.streamPuzzleRecord(record, markStored),
+				streamUpdate: (challenge, markStored) => this.centralStreamer?.streamPuzzleUpdate(() => this.getPuzzleCaptchaRecordByChallenge(challenge), markStored)
+			};
+			case CaptchaType.iconOrder: return {
+				table: "iconordercaptcha",
+				label: "IconOrderCaptcha",
+				captchaType,
+				answerProjection: {
+					targets: 1,
+					tolerance: 1,
+					clicks: 1,
+					iconOrderEvents: 1
+				},
+				streamRecord: (record, markStored) => this.centralStreamer?.streamIconOrderRecord(record, markStored),
+				streamUpdate: (challenge, markStored) => this.centralStreamer?.streamIconOrderUpdate(() => this.getIconOrderCaptchaRecordByChallenge(challenge), markStored)
+			};
+			case CaptchaType.audio: return {
+				table: "audiocaptcha",
+				label: "AudioCaptcha",
+				captchaType,
+				answerProjection: {
+					answer: 1,
+					submittedAnswer: 1,
+					replays: 1,
+					audioEvents: 1
+				},
+				streamRecord: (record, markStored) => this.centralStreamer?.streamAudioRecord(record, markStored),
+				streamUpdate: (challenge, markStored) => this.centralStreamer?.streamAudioUpdate(() => this.getAudioCaptchaRecordByChallenge(challenge), markStored)
+			};
+		}
+	}
+	markInteractiveRecordStored(collection, challenge) {
+		return (ts) => this.tables[collection.table].updateOne({
 			challenge,
-			userAccount: components.userAccount,
-			dappAccount: components.dappAccount,
-			requestedAtTimestamp: new Date(components.requestedAtTimestamp),
-			ipAddress,
-			headers,
-			ja4,
-			result: { status: CaptchaStatus.pending },
-			userSubmitted: false,
-			serverChecked: false,
-			targetX,
-			targetY,
-			originX,
-			originY,
-			tolerance,
-			providerSignature,
-			lastUpdatedTimestamp: /* @__PURE__ */ new Date(),
-			pendingStage: true,
-			sessionId,
-			ipInfo
-		};
+			lastUpdatedTimestamp: { $lte: ts }
+		}, {
+			$set: { storedAtTimestamp: ts },
+			$unset: { pendingStage: 1 }
+		}).then(() => {});
+	}
+	streamInteractiveUpdate(collection, challenge) {
+		collection.streamUpdate(challenge, this.markInteractiveRecordStored(collection, challenge));
+	}
+	async storeInteractiveCaptchaRecord(collection, record) {
+		const tables = this.getTables();
+		const { challenge, ipInfo } = record;
 		try {
-			await tables.puzzlecaptcha.create(puzzleCaptchaRecord);
+			await tables[collection.table].create(record);
 			this.logger.info(() => ({
 				data: {
 					challenge,
 					countryCode: ipInfo?.isValid ? ipInfo.countryCode : void 0
 				},
-				msg: "PuzzleCaptcha record added successfully"
+				msg: `${collection.label} record added successfully`
 			}));
-			this.centralStreamer?.streamPuzzleRecord(puzzleCaptchaRecord, (ts) => this.tables.puzzlecaptcha.updateOne({
-				challenge,
-				lastUpdatedTimestamp: { $lte: ts }
-			}, {
-				$set: { storedAtTimestamp: ts },
-				$unset: { pendingStage: 1 }
-			}).then(() => {}));
+			collection.streamRecord(record, this.markInteractiveRecordStored(collection, challenge));
 		} catch (error) {
 			const err = new ProsopoDBError("DATABASE.CAPTCHA_UPDATE_FAILED", {
 				context: {
@@ -691,24 +731,60 @@ var ProviderDatabase = class ProviderDatabase extends MongoDatabase {
 			});
 			this.logger.error(() => ({
 				err: error,
-				msg: "Failed to add PuzzleCaptcha record"
+				msg: `Failed to add ${collection.label} record`
 			}));
 			throw err;
 		}
 	}
-	/**
-	* @description Retrieves a Puzzle Captcha record by its challenge string.
-	* @param {string} challenge The challenge string to search for.
-	* @returns {Promise<PuzzleCaptchaRecord | null>} A promise that resolves with the found record or null if not found.
-	*/
-	async getPuzzleCaptchaRecordByChallenge(challenge) {
+	pendingInteractiveRecord(challenge, components, providerSignature, ipAddress, headers, ja4, sessionId, ipInfo) {
+		return {
+			challenge,
+			userAccount: components.userAccount,
+			dappAccount: components.dappAccount,
+			requestedAtTimestamp: new Date(components.requestedAtTimestamp),
+			ipAddress,
+			headers,
+			ja4,
+			result: { status: CaptchaStatus.pending },
+			userSubmitted: false,
+			serverChecked: false,
+			providerSignature,
+			lastUpdatedTimestamp: /* @__PURE__ */ new Date(),
+			pendingStage: true,
+			sessionId,
+			ipInfo
+		};
+	}
+	async storePuzzleCaptchaRecord(challenge, components, targetX, targetY, originX, originY, tolerance, providerSignature, ipAddress, headers, ja4, sessionId, ipInfo) {
+		await this.storeInteractiveCaptchaRecord(this.interactiveCollection(CaptchaType.puzzle), {
+			...this.pendingInteractiveRecord(challenge, components, providerSignature, ipAddress, headers, ja4, sessionId, ipInfo),
+			tolerance,
+			targetX,
+			targetY,
+			originX,
+			originY
+		});
+	}
+	async storeAudioCaptchaRecord(challenge, components, answer, providerSignature, ipAddress, headers, ja4, sessionId, ipInfo) {
+		await this.storeInteractiveCaptchaRecord(this.interactiveCollection(CaptchaType.audio), {
+			...this.pendingInteractiveRecord(challenge, components, providerSignature, ipAddress, headers, ja4, sessionId, ipInfo),
+			answer
+		});
+	}
+	async storeIconOrderCaptchaRecord(challenge, components, targets, tolerance, providerSignature, ipAddress, headers, ja4, sessionId, ipInfo) {
+		await this.storeInteractiveCaptchaRecord(this.interactiveCollection(CaptchaType.iconOrder), {
+			...this.pendingInteractiveRecord(challenge, components, providerSignature, ipAddress, headers, ja4, sessionId, ipInfo),
+			targets,
+			tolerance
+		});
+	}
+	async getInteractiveCaptchaRecordByChallenge(collection, challenge, failedFuncName) {
 		if (!this.tables) throw new ProsopoDBError("DATABASE.DATABASE_UNDEFINED", {
-			context: { failedFuncName: this.getPuzzleCaptchaRecordByChallenge.name },
+			context: { failedFuncName },
 			logger: this.logger
 		});
 		try {
-			const filter = { challenge };
-			const record = await this.tables.puzzlecaptcha.findOne(filter, {
+			const record = await this.tables[collection.table].findOne({ challenge }, {
 				challenge: 1,
 				userAccount: 1,
 				dappAccount: 1,
@@ -718,12 +794,6 @@ var ProviderDatabase = class ProviderDatabase extends MongoDatabase {
 				headers: 1,
 				ja4: 1,
 				result: 1,
-				targetX: 1,
-				targetY: 1,
-				originX: 1,
-				originY: 1,
-				tolerance: 1,
-				puzzleEvents: 1,
 				sessionId: 1,
 				ipInfo: 1,
 				deviceCapability: 1,
@@ -731,18 +801,19 @@ var ProviderDatabase = class ProviderDatabase extends MongoDatabase {
 				serverChecked: 1,
 				userSubmitted: 1,
 				coords: 1,
-				clientMetaData: 1
+				clientMetaData: 1,
+				...collection.answerProjection
 			}).lean();
 			if (record) {
 				this.logger.info(() => ({
 					data: { challenge },
-					msg: "PuzzleCaptcha record retrieved successfully"
+					msg: `${collection.label} record retrieved successfully`
 				}));
 				return record;
 			}
 			this.logger.info(() => ({
 				data: { challenge },
-				msg: "No PuzzleCaptcha record found"
+				msg: `No ${collection.label} record found`
 			}));
 			return null;
 		} catch (error) {
@@ -755,23 +826,71 @@ var ProviderDatabase = class ProviderDatabase extends MongoDatabase {
 			});
 			this.logger.error(() => ({
 				err,
-				msg: "Failed to retrieve PuzzleCaptcha record"
+				msg: `Failed to retrieve ${collection.label} record`
 			}));
 			throw err;
 		}
 	}
 	/**
-	* @description Updates a Puzzle Captcha record result in the database.
-	* @param {string} challenge The challenge string of the captcha to be updated.
-	* @param result
-	* @param serverChecked
-	* @param userSubmitted
-	* @param userSignature
-	* @param coords
-	* @param lastUpdatedTimestamp
-	* @returns {Promise<void>} A promise that resolves when the record is updated.
+	* @description Retrieves a Puzzle Captcha record by its challenge string.
+	* @param {string} challenge The challenge string to search for.
+	* @returns {Promise<PuzzleCaptchaRecord | null>} A promise that resolves with the found record or null if not found.
 	*/
-	async updatePuzzleCaptchaRecordResult(challenge, result, serverChecked = false, userSubmitted = false, userSignature, coords, lastUpdatedTimestamp) {
+	async getPuzzleCaptchaRecordByChallenge(challenge) {
+		return this.getInteractiveCaptchaRecordByChallenge(this.interactiveCollection(CaptchaType.puzzle), challenge, this.getPuzzleCaptchaRecordByChallenge.name);
+	}
+	async getIconOrderCaptchaRecordByChallenge(challenge) {
+		return this.getInteractiveCaptchaRecordByChallenge(this.interactiveCollection(CaptchaType.iconOrder), challenge, this.getIconOrderCaptchaRecordByChallenge.name);
+	}
+	async getAudioCaptchaRecordByChallenge(challenge) {
+		return this.getInteractiveCaptchaRecordByChallenge(this.interactiveCollection(CaptchaType.audio), challenge, this.getAudioCaptchaRecordByChallenge.name);
+	}
+	/**
+	* The filter is the guard: of N concurrent submitters only one matches
+	* `userSubmitted: { $ne: true }`, where a read-then-check would let them
+	* all through to be graded. `submittedAtTimestamp` is stamped here so the
+	* record is consistent even if the caller dies before writing a result.
+	*/
+	async claimInteractiveCaptchaSubmission(collection, challenge) {
+		const tables = this.getTables();
+		try {
+			const won = (await tables[collection.table].updateOne({
+				challenge,
+				userSubmitted: { $ne: true }
+			}, { $set: {
+				userSubmitted: true,
+				submittedAtTimestamp: /* @__PURE__ */ new Date()
+			} })).modifiedCount === 1;
+			this.logger.info(() => ({
+				data: {
+					challenge,
+					won
+				},
+				msg: won ? `${collection.label} submission claimed` : `${collection.label} submission already claimed`
+			}));
+			return won;
+		} catch (error) {
+			const err = new ProsopoDBError("DATABASE.CAPTCHA_UPDATE_FAILED", {
+				context: {
+					error,
+					challenge
+				},
+				logger: this.logger
+			});
+			this.logger.error(() => ({
+				err,
+				msg: `Failed to claim ${collection.label} submission`
+			}));
+			throw err;
+		}
+	}
+	async claimIconOrderCaptchaSubmission(challenge) {
+		return this.claimInteractiveCaptchaSubmission(this.interactiveCollection(CaptchaType.iconOrder), challenge);
+	}
+	async claimAudioCaptchaSubmission(challenge) {
+		return this.claimInteractiveCaptchaSubmission(this.interactiveCollection(CaptchaType.audio), challenge);
+	}
+	async updateInteractiveCaptchaRecordResult(collection, challenge, result, serverChecked, userSubmitted, userSignature, coords, lastUpdatedTimestamp) {
 		const tables = this.getTables();
 		const timestamp = lastUpdatedTimestamp ?? /* @__PURE__ */ new Date();
 		const isDisapproved = result.status === CaptchaStatus.disapproved;
@@ -783,13 +902,13 @@ var ProviderDatabase = class ProviderDatabase extends MongoDatabase {
 			userSignature,
 			lastUpdatedTimestamp: timestamp,
 			pendingStage: true,
-			blocked: isBlockingCaptchaResult(CaptchaType.puzzle, result),
+			blocked: isBlockingCaptchaResult(collection.captchaType, result),
 			...coords && { coords },
 			...userSubmitted && { submittedAtTimestamp: timestamp },
 			...isDisapproved && { failedAtTimestamp: timestamp }
 		};
 		try {
-			if ((await tables.puzzlecaptcha.updateOne({ challenge }, { $set: setStage })).matchedCount === 0) {
+			if ((await tables[collection.table].updateOne({ challenge }, { $set: setStage })).matchedCount === 0) {
 				const err = new ProsopoDBError("DATABASE.CAPTCHA_GET_FAILED", {
 					context: {
 						challenge,
@@ -799,7 +918,7 @@ var ProviderDatabase = class ProviderDatabase extends MongoDatabase {
 				});
 				this.logger.info(() => ({
 					err,
-					msg: "No PuzzleCaptcha record found to update"
+					msg: `No ${collection.label} record found to update`
 				}));
 				throw err;
 			}
@@ -808,15 +927,9 @@ var ProviderDatabase = class ProviderDatabase extends MongoDatabase {
 					challenge,
 					...setStage
 				},
-				msg: "PuzzleCaptcha record updated successfully"
+				msg: `${collection.label} record updated successfully`
 			}));
-			this.centralStreamer?.streamPuzzleUpdate(() => this.getPuzzleCaptchaRecordByChallenge(challenge), (ts) => this.tables.puzzlecaptcha.updateOne({
-				challenge,
-				lastUpdatedTimestamp: { $lte: ts }
-			}, {
-				$set: { storedAtTimestamp: ts },
-				$unset: { pendingStage: 1 }
-			}).then(() => {}));
+			this.streamInteractiveUpdate(collection, challenge);
 		} catch (error) {
 			const err = new ProsopoDBError("DATABASE.CAPTCHA_UPDATE_FAILED", {
 				context: {
@@ -828,12 +941,32 @@ var ProviderDatabase = class ProviderDatabase extends MongoDatabase {
 			});
 			this.logger.error(() => ({
 				err,
-				msg: "Failed to update PuzzleCaptcha record"
+				msg: `Failed to update ${collection.label} record`
 			}));
 			throw err;
 		}
 	}
-	async updatePuzzleCaptchaRecord(challenge, updates) {
+	/**
+	* @description Updates a Puzzle Captcha record result in the database.
+	* @param {string} challenge The challenge string of the captcha to be updated.
+	* @param result
+	* @param serverChecked
+	* @param userSubmitted
+	* @param userSignature
+	* @param coords
+	* @param lastUpdatedTimestamp
+	* @returns {Promise<void>} A promise that resolves when the record is updated.
+	*/
+	async updatePuzzleCaptchaRecordResult(challenge, result, serverChecked = false, userSubmitted = false, userSignature, coords, lastUpdatedTimestamp) {
+		await this.updateInteractiveCaptchaRecordResult(this.interactiveCollection(CaptchaType.puzzle), challenge, result, serverChecked, userSubmitted, userSignature, coords, lastUpdatedTimestamp);
+	}
+	async updateIconOrderCaptchaRecordResult(challenge, result, serverChecked = false, userSubmitted = false, userSignature, coords, lastUpdatedTimestamp) {
+		await this.updateInteractiveCaptchaRecordResult(this.interactiveCollection(CaptchaType.iconOrder), challenge, result, serverChecked, userSubmitted, userSignature, coords, lastUpdatedTimestamp);
+	}
+	async updateAudioCaptchaRecordResult(challenge, result, serverChecked = false, userSubmitted = false, userSignature, coords, lastUpdatedTimestamp) {
+		await this.updateInteractiveCaptchaRecordResult(this.interactiveCollection(CaptchaType.audio), challenge, result, serverChecked, userSubmitted, userSignature, coords, lastUpdatedTimestamp);
+	}
+	async updateInteractiveCaptchaRecord(collection, challenge, updates) {
 		const tables = this.getTables();
 		const timestamp = /* @__PURE__ */ new Date();
 		const baseSet = {
@@ -843,19 +976,22 @@ var ProviderDatabase = class ProviderDatabase extends MongoDatabase {
 			...updates.userSubmitted === true && { submittedAtTimestamp: timestamp },
 			...updates.result?.status === CaptchaStatus.disapproved && { failedAtTimestamp: timestamp }
 		};
-		await tables.puzzlecaptcha.updateOne({ challenge }, { $set: baseSet });
-		this.centralStreamer?.streamPuzzleUpdate(() => this.getPuzzleCaptchaRecordByChallenge(challenge), (ts) => this.tables.puzzlecaptcha.updateOne({
-			challenge,
-			lastUpdatedTimestamp: { $lte: ts }
-		}, {
-			$set: { storedAtTimestamp: ts },
-			$unset: { pendingStage: 1 }
-		}).then(() => {}));
+		await tables[collection.table].updateOne({ challenge }, { $set: baseSet });
+		this.streamInteractiveUpdate(collection, challenge);
 	}
-	async markPuzzleCaptchaRecordChecked(challenge) {
+	async updatePuzzleCaptchaRecord(challenge, updates) {
+		await this.updateInteractiveCaptchaRecord(this.interactiveCollection(CaptchaType.puzzle), challenge, updates);
+	}
+	async updateIconOrderCaptchaRecord(challenge, updates) {
+		await this.updateInteractiveCaptchaRecord(this.interactiveCollection(CaptchaType.iconOrder), challenge, updates);
+	}
+	async updateAudioCaptchaRecord(challenge, updates) {
+		await this.updateInteractiveCaptchaRecord(this.interactiveCollection(CaptchaType.audio), challenge, updates);
+	}
+	async markInteractiveCaptchaRecordChecked(collection, challenge) {
 		const tables = this.getTables();
 		const timestamp = /* @__PURE__ */ new Date();
-		if ((await tables.puzzlecaptcha.updateOne({
+		if ((await tables[collection.table].updateOne({
 			challenge,
 			serverChecked: { $ne: true }
 		}, { $set: {
@@ -864,15 +1000,18 @@ var ProviderDatabase = class ProviderDatabase extends MongoDatabase {
 			verifiedAtTimestamp: timestamp,
 			pendingStage: true
 		} })).modifiedCount === 0) return false;
-		this.centralStreamer?.streamPuzzleUpdate(() => this.getPuzzleCaptchaRecordByChallenge(challenge), (ts) => this.tables.puzzlecaptcha.updateOne({
-			challenge,
-			lastUpdatedTimestamp: { $lte: ts }
-		}, {
-			$set: { storedAtTimestamp: ts },
-			$unset: { pendingStage: 1 }
-		}).then(() => {}));
+		this.streamInteractiveUpdate(collection, challenge);
 		return true;
 	}
+	async markIconOrderCaptchaRecordChecked(challenge) {
+		return this.markInteractiveCaptchaRecordChecked(this.interactiveCollection(CaptchaType.iconOrder), challenge);
+	}
+	async markAudioCaptchaRecordChecked(challenge) {
+		return this.markInteractiveCaptchaRecordChecked(this.interactiveCollection(CaptchaType.audio), challenge);
+	}
+	async markPuzzleCaptchaRecordChecked(challenge) {
+		return this.markInteractiveCaptchaRecordChecked(this.interactiveCollection(CaptchaType.puzzle), challenge);
+	}
 	/** @description Get serverChecked Dapp User image captcha commitments from the commitments table
 	*/
 	async getCheckedDappUserCommitments() {
@@ -966,13 +1105,13 @@ var ProviderDatabase = class ProviderDatabase extends MongoDatabase {
 		} }], { updatePipeline: true });
 	}
 	/**
-	* Counts server-checked captcha records across image (`commitment`),
-	* PoW and puzzle collections whose `metadata.emailNormalised` matches.
-	* Each collection carries the same partial index
-	* (`spamEmailCount_partial`) so all three counts hit index-only scans.
-	* The three counts are summed — one dapp can mix captcha types over
-	* time, and per-email rate limits should apply across the whole
-	* verified surface, not per-type.
+	* Counts server-checked captcha records across the image (`commitment`),
+	* PoW, puzzle and icon-order collections whose `metadata.emailNormalised`
+	* matches. Each collection carries the same partial index
+	* (`spamEmailCount_partial`) so every count hits an index-only scan. The
+	* counts are summed — one dapp can mix captcha types over time, and
+	* per-email rate limits should apply across the whole verified surface,
+	* not per-type.
 	*/
 	async countCommitmentsByNormalisedEmail(dappAccount, emailNormalised) {
 		if (!emailNormalised) return 0;
@@ -982,12 +1121,13 @@ var ProviderDatabase = class ProviderDatabase extends MongoDatabase {
 			serverChecked: true,
 			"metadata.emailNormalised": emailNormalised
 		};
-		const [imgCount, powCount, puzzleCount] = await Promise.all([
+		return (await Promise.all([
 			tables.commitment.countDocuments(filter),
 			tables.powcaptcha.countDocuments(filter),
-			tables.puzzlecaptcha.countDocuments(filter)
-		]);
-		return imgCount + powCount + puzzleCount;
+			tables.puzzlecaptcha.countDocuments(filter),
+			tables.iconordercaptcha.countDocuments(filter),
+			tables.audiocaptcha.countDocuments(filter)
+		])).reduce((total, count) => total + count, 0);
 	}
 	/**
 	* @description Get Dapp User PoW captcha commitments that have not been counted towards the client's total