feat(backend): the utilities and services required for the pow feature

src/frontend/src/lib/schema/post-message.schema.ts

@@ -189,3 +189,92 @@ export const inferPostMessageSchema = <T extends z.ZodTypeAny>(dataSchema: T) =>
 		msg: z.union([PostMessageRequestSchema, PostMessageResponseSchema]),
 		data: dataSchema.optional()
 	});
+
+// -----------------------------------------------------------------------------------------------
+// The generic data structures which are required to implement the Short Polling (request-response)
+// design pattern used for a simplified communication between the worker(s) and the web application
+// The data structure for a request or response to/from a canister call is more or less 1:1 propagated
+// by the data structure defined by the schema.
+// -----------------------------------------------------------------------------------------------
+/**
+ * Base schema for all post messages
+ */
+export const PostMessageBaseSchema = z.object({
+	msg: z.string(), // Message type
+	requestId: z.string() // Unique identifier for tracking requests and responses
+});
+
+/**
+ * Base schema for all post message requests
+ */
+export const PostMessageRequestBaseSchema = PostMessageBaseSchema.extend({
+	type: z.literal('request'), // Specifies this is a request
+	data: z.unknown().optional() // Optional data payload
+});
+
+export const PostMessageErrorSchema = z.string();
+
+/**
+ * Base schema for all post message responses
+ */
+export const PostMessageResponseBaseSchema = PostMessageBaseSchema.extend({
+	type: z.literal('response'),
+	result: z.union([z.object({ Ok: z.unknown() }), z.object({ Err: PostMessageErrorSchema })])
+});
+
+export const CreatePowChallengeRequestDataSchema = z.object({});
+
+export const PostMessageCreatePowChallengeRequestSchema = PostMessageRequestBaseSchema.extend({
+	msg: z.literal('CreatePowChallengeRequest'),
+	data: CreatePowChallengeRequestDataSchema.optional()
+});
+
+export const CreatePowChallengeResponseResultSchema = z.object({
+	difficulty: z.number(),
+	start_timestamp_ms: z.bigint(),
+	expiry_timestamp_ms: z.bigint()
+});
+
+export const PostMessageCreatePowChallengeResponseSchema = PostMessageResponseBaseSchema.extend({
+	msg: z.literal('CreatePowChallengeResponse'),
+	result: z.union([
+		z.object({ Ok: CreatePowChallengeResponseResultSchema }),
+		z.object({ Err: PostMessageErrorSchema })
+	])
+});
+
+export const AllowSigningRequestDataSchema = z.object({
+	nonce: z.bigint()
+});
+
+export const PostMessageAllowSigningRequestSchema = PostMessageRequestBaseSchema.extend({
+	msg: z.literal('AllowSigningRequest'),
+	data: AllowSigningRequestDataSchema
+});
+
+export const ChallengeCompletionSchema = z.object({
+	solved_duration_ms: z.bigint(),
+	next_allowance_ms: z.bigint(),
+	next_difficulty: z.number(),
+	current_difficulty: z.number()
+});
+
+const AllowSigningStatusSchema = z.union([
+	z.object({ Skipped: z.null() }),
+	z.object({ Failed: z.null() }),
+	z.object({ Executed: z.null() })
+]);
+
+export const AllowSigningResponseResultSchema = z.object({
+	status: AllowSigningStatusSchema, // Use the corrected schema for status
+	challenge_completion: z.array(z.any()).optional(), // Assuming ChallengeCompletion is modeled correctly elsewhere
+	allowed_cycles: z.bigint()
+});
+
+export const PostMessageAllowSigningResponseSchema = PostMessageResponseBaseSchema.extend({
+	msg: z.literal('AllowSigningResponse'),
+	result: z.union([
+		z.object({ Ok: AllowSigningResponseResultSchema }),
+		z.object({ Err: PostMessageErrorSchema })
+	])
+});

src/frontend/src/lib/services/pow.services.ts

@@ -0,0 +1,79 @@
+import type {
+	AllowSigningRequest,
+	Result_2 as AllowSigningResult,
+	Result_6 as CreateChallengeResult
+} from '$declarations/backend/backend.did';
+import { allowSigningResult, createPowChallenge } from '$lib/api/backend.api';
+import type { OptionIdentity } from '$lib/types/identity';
+import { hashToHex } from '$lib/utils/crypto.utils';
+
+function getTimestampNowMs(): bigint {
+	return BigInt(Date.now());
+}
+
+export const solvePowChallenge = async ({
+	timestamp,
+	difficulty
+}: {
+	timestamp: bigint;
+	difficulty: number;
+}): Promise<number> => {
+	if (difficulty <= 0) {
+		throw new Error('Difficulty must be greater than zero');
+	}
+
+	let nonce = 0;
+	const target = Math.floor(0xffffffff / difficulty);
+
+	// is only used to measure the effective execution time
+	const startTimestampMs = getTimestampNowMs();
+
+	while (true) {
+		const challengeStr = `${timestamp}.${nonce}`;
+		const hashHex = await hashToHex(challengeStr); // Using the new hashToHex function
+		const prefix = parseInt(hashHex.slice(0, 8), 16); // Only consider the first 4 bytes
+		if (prefix <= target) {
+			break;
+		}
+		nonce++;
+	}
+
+	const solveTimestampMs = getTimestampNowMs() - startTimestampMs;
+	console.error(`Pow Challenge solved in ${Number(solveTimestampMs) / 1e3} seconds.`);
+	return nonce;
+};
+
+export const _createPowChallenge = async ({
+	identity
+}: {
+	identity: OptionIdentity;
+}): Promise<CreateChallengeResult> => {
+	try {
+		return await createPowChallenge({ identity });
+	} catch (error) {
+		return {
+			Err: {
+				Other: `UnexpectedError: ${error}`
+			}
+		};
+	}
+};
+
+export const _allowSigning = async ({
+	identity,
+	request
+}: {
+	identity: OptionIdentity;
+	request?: AllowSigningRequest;
+}): Promise<AllowSigningResult> => {
+	try {
+		return await allowSigningResult({ identity, request });
+	} catch (error) {
+		// Ensure the `Err` matches the `CreateChallengeError` type
+		return {
+			Err: {
+				Other: `UnexpectedError: ${error}`
+			}
+		};
+	}
+};

src/frontend/src/lib/types/post-message.ts

@@ -1,4 +1,10 @@
 import type {
+	inferPostMessageSchema,
+	PostMessageAllowSigningRequestSchema,
+	PostMessageAllowSigningResponseSchema,
+	PostMessageBaseSchema,
+	PostMessageCreatePowChallengeRequestSchema,
+	PostMessageCreatePowChallengeResponseSchema,
 	PostMessageDataRequestBtcSchema,
 	PostMessageDataRequestExchangeTimerSchema,
 	PostMessageDataRequestIcCkBTCUpdateBalanceSchema,
@@ -16,10 +22,11 @@ import type {
 	PostMessageDataResponseWalletCleanUpSchema,
 	PostMessageDataResponseWalletSchema,
 	PostMessageJsonDataResponseSchema,
+	PostMessageRequestBaseSchema,
+	PostMessageResponseBaseSchema,
 	PostMessageResponseSchema,
 	PostMessageResponseStatusSchema,
-	PostMessageSyncStateSchema,
-	inferPostMessageSchema
+	PostMessageSyncStateSchema
 } from '$lib/schema/post-message.schema';
 import type * as z from 'zod';
 import type { ZodType } from 'zod';
@@ -78,3 +85,20 @@ export type PostMessageDataResponseBTCAddress = z.infer<
 export type PostMessage<T extends PostMessageDataRequest | PostMessageDataResponse> = z.infer<
 	ReturnType<typeof inferPostMessageSchema<ZodType<T>>>
 >;
+
+// -----------------------------------------------------------------------------------------------
+// The post message types used for short polling between:
+// pow.worker.ts <--->  worker.pow.services.ts
+// -----------------------------------------------------------------------------------------------
+// Base Types
+export type PostMessageBase = z.infer<typeof PostMessageBaseSchema>;
+export type PostMessageRequestBase = z.infer<typeof PostMessageRequestBaseSchema>;
+export type PostMessageResponseBase = z.infer<typeof PostMessageResponseBaseSchema>;
+export type PostMessageCreatePowChallengeRequest = z.infer<
+	typeof PostMessageCreatePowChallengeRequestSchema
+>;
+export type PostMessageCreatePowChallengeResponse = z.infer<
+	typeof PostMessageCreatePowChallengeResponseSchema
+>;
+export type PostMessageAllowSigningRequest = z.infer<typeof PostMessageAllowSigningRequestSchema>;
+export type PostMessageAllowSigningResponse = z.infer<typeof PostMessageAllowSigningResponseSchema>;

src/frontend/src/lib/utils/crypto.utils.ts

@@ -0,0 +1,25 @@
+const textEncoder = new TextEncoder();
+
+/**
+ * Hashes the given input string using the SHA-256 algorithm.
+ */
+export async function sha256(input: string): Promise<ArrayBuffer> {
+	return await crypto.subtle.digest('SHA-256', textEncoder.encode(input));
+}
+
+/**
+ * Converts an ArrayBuffer to its hexadecimal string representation.
+ */
+export function bufferToHex(buffer: ArrayBuffer): string {
+	return Array.from(new Uint8Array(buffer))
+		.map((byte) => byte.toString(16).padStart(2, '0'))
+		.join('');
+}
+
+/**
+ * Combines the hashing and hex conversion of a string into a single function.
+ */
+export async function hashToHex(input: string): Promise<string> {
+	const hashBuffer = await sha256(input);
+	return bufferToHex(hashBuffer);
+}

src/frontend/src/lib/utils/worker.utils.ts

@@ -0,0 +1,68 @@
+import type { PostMessageRequestBase } from '$lib/types/post-message';
+import type { z } from 'zod';
+
+const responseHandlers = new Map<string, (data: unknown) => void>();
+
+export function routeWorkerResponse(event: MessageEvent): boolean {
+	//const { type } = event.data;
+	const { type, requestId } = event.data;
+
+	// Exit immediately if 'type' is missing or not equal to 'response'
+	if (!type || type !== 'response') {
+		console.error("Invalid message type. Expected 'response', but got:", event.data);
+		return false;
+	}
+
+	console.warn('Valid data received: ', event.data);
+
+	const handler = responseHandlers.get(requestId);
+	if (handler) {
+		handler(event.data);
+		responseHandlers.delete(requestId);
+		return true;
+	}
+	console.warn('No handler found for event', requestId);
+	return false;
+}
+
+/**
+ * Sends a typed request to the worker and awaits the fully typed response envelope (T).
+ */
+export function sendMessageRequest<T>({
+	worker,
+	msg,
+	data,
+	schema
+}: {
+	worker: Worker;
+	msg: string;
+	data: object;
+	schema: z.ZodType<T>;
+}): Promise<T> {
+	const requestId = crypto.randomUUID();
+
+	// Explicitly type the payload as PostMessageRequestBase
+	const payload: PostMessageRequestBase = {
+		msg,
+		requestId,
+		type: 'request',
+		data
+	};
+
+	return new Promise((resolve, reject) => {
+		responseHandlers.set(requestId, (rawResponse: unknown) => {
+			const parsed = schema.safeParse(rawResponse as PostMessageRequestBase);
+			if (!parsed.success) {
+				console.error(
+					`Invalid response for message '${msg}' (Request ID: ${requestId}):`,
+					parsed.error.format()
+				);
+				reject(parsed.error);
+				return;
+			}
+			resolve(parsed.data);
+		});
+
+		worker.postMessage(payload); // Send the typed payload
+	});
+}

src/frontend/src/tests/lib/utils/crypto.utils.spec.ts

@@ -0,0 +1,24 @@
+import { bufferToHex, hashToHex } from '$lib/utils/crypto.utils';
+import { describe, expect, it } from 'vitest';
+
+describe('crypto.utils', () => {
+	describe('bufferToHex', () => {
+		it('should convert an ArrayBuffer to a hexadecimal string', () => {
+			const buffer = new Uint8Array([1, 255, 16, 32]).buffer;
+			const hex = bufferToHex(buffer);
+
+			expect(hex).toBe('01ff1020');
+		});
+	});
+
+	describe('hashToHex', () => {
+		it('should hash a string and return its hex representation', async () => {
+			const input = 'hash-to-hex-test';
+			const hex = await hashToHex(input);
+
+			expect(typeof hex).toBe('string');
+
+			expect(hex.length).toBe(64);
+		});
+	});
+});