feat: Create verifications module to streamline auth_email_* and auth_sms_*

Author: Blckbrry-Pi

modules/verifications/db/schema.ts

@@ -0,0 +1,34 @@
+import { schema, Query } from "./schema.gen.ts";
+
+export const verifications = schema.table('verifications', {
+  id: Query.uuid("id").primaryKey().defaultRandom(),
+
+  data: Query.jsonb("data").notNull(),
+
+  code: Query.text("code").notNull().unique(),
+  token: Query.text("token").notNull().unique(),
+
+  attemptCount: Query.integer("attempt_count").notNull().default(0),
+  maxAttemptCount: Query.integer("max_attempt_count").notNull(),
+
+  createdAt: Query.timestamp("created_at").notNull().defaultNow(),
+  expireAt: Query.timestamp("expire_at").notNull(),
+});
+
+export const oldVerifications = schema.table('old_verifications', {
+  id: Query.uuid("id").primaryKey(),
+
+  data: Query.jsonb("data").notNull(),
+
+  code: Query.text("code").notNull().unique(),
+  token: Query.text("token").notNull().unique(),
+
+  attemptsCount: Query.integer("attempt_count").notNull(),
+  wasCompleted: Query.boolean("was_completed").notNull(),
+
+  createdAt: Query.timestamp("created_at").notNull(),
+  invalidatedAt: Query.timestamp("invalidated_at"),
+  expiredAt: Query.timestamp("expired_at"),
+  completedAt: Query.timestamp("completed_at"),
+});
+

modules/verifications/module.json

@@ -0,0 +1,60 @@
+{
+	"status": "stable",
+	"name": "Verifications",
+	"description": "INTERNAL ONLY module — helper for OTP verifications (email/sms)",
+	"icon": "key",
+	"tags": [
+		"auth"
+	],
+	"authors": [
+		"Blckbrry-Pi"
+	],
+	"dependencies": {
+		"tokens": {}
+	},
+	"scripts": {
+		"create": {
+			"name": "Create Verification",
+			"public": false
+		},
+		"attempt": {
+			"name": "Attempt to Complete Verification",
+			"public": false
+		},
+		"invalidate": {
+			"name": "Invalidate Verification",
+			"public": false
+		},
+		"get": {
+			"name": "Get Verification Information",
+			"public": false
+		}
+	},
+	"errors": {
+		"unable_to_generate_unique_code": {
+			"name": "Unable to Generate Unique Code",
+			"description": "When generating a new code for a new verification, the script was unable to find a unique one.",
+			"internal": true
+		},
+		"no_verification_found": {
+			"name": "No verification found matching the required parameters",
+			"description": "When attempting to find a verification, the database returned no matching results.",
+			"internal": true
+		},
+		"failed_to_create": {
+			"name": "Failed to Create New Verification",
+			"description": "There was a database error while creating a new verification.",
+			"internal": true
+		},
+		"failed_to_update": {
+			"name": "Failed to Update Existing Verification",
+			"description": "There was a database error while updating the information on an existing verification.",
+			"internal": true
+		},
+		"unknown_err": {
+			"name": "Unknown Error",
+			"description": "There was an unexpected error of an unknown type.",
+			"internal": true
+		}
+	}
+}

modules/verifications/scripts/attempt.ts

@@ -0,0 +1,58 @@
+import { ScriptContext, Query, Database, RuntimeError } from "../module.gen.ts";
+import { complete, moveToOldIfNecessary } from "../utils/migrate.ts";
+
+export interface Request {
+	token: string;
+	code: string;
+}
+
+export interface Response {
+	succeeded: boolean;
+	canTryAgain: boolean;
+	data: unknown;
+}
+
+export async function run(ctx: ScriptContext, req: Request): Promise<Response> {
+	try {
+		const [verification] = await ctx.db.select()
+			.from(Database.verifications)
+			.where(Query.eq(Database.verifications.token, req.token));
+	
+		if (!verification) throw new RuntimeError("no_verification_found");
+		if (await moveToOldIfNecessary(ctx, verification.code)) throw new RuntimeError("no_verification_found");
+	
+		let codeDiffers = Number(req.code.length !== verification.code.length);
+		for (let i = 0; i < verification.code.length; i++) {
+			codeDiffers |= verification.code.charCodeAt(i) ^ req.code.charCodeAt(i);
+		}
+
+		if (codeDiffers) {
+			await ctx.db.update(Database.verifications)
+				.set({
+					attemptCount: Query.sql`${Database.verifications.attemptCount} + 1`,
+				})
+				.where(Query.eq(Database.verifications.id, verification.id)).returning();
+			const canTryAgain = !await moveToOldIfNecessary(ctx, verification.code);
+			return {
+				succeeded: false,
+				canTryAgain,
+				data: verification.data,
+			}
+		} else {
+			await complete(ctx, verification.id);
+			return {
+				succeeded: true,
+				canTryAgain: false,
+				data: verification.data,
+			}
+		}
+	} catch (e) {
+		if (e instanceof RuntimeError) {
+			throw e;
+		} else if (e instanceof Query.DrizzleError) {
+			throw new RuntimeError("failed_to_update");
+		} else {
+			throw new RuntimeError("unknown_err");
+		}
+	}
+}

modules/verifications/scripts/create.ts

@@ -0,0 +1,69 @@
+import { ScriptContext, Module, Database, RuntimeError, Query } from "../module.gen.ts";
+import { moveToOldIfNecessary } from "../utils/migrate.ts";
+
+export interface Request {
+	data: unknown;
+	maxAttempts?: number;
+	expireAt?: string;
+}
+
+export interface Response {
+	id: string;
+	code: string;
+	token: string;
+}
+
+// This is very generous— we should definitely flush old verifications however
+const MAX_ATTEMPTS = 20;
+
+export async function run(ctx: ScriptContext, req: Request): Promise<Response> {
+	const failedCodes = [];
+	try {
+		for (let i = 0; i < MAX_ATTEMPTS; i++) {
+			// Generate code + token cryptographically using the `tokens` public
+			// functions
+			const code = Module.tokens.generateRandomCodeSecure("0123456789", 8);
+			const token = Module.tokens.genSecureId(32, Module.tokens.SecureIdFormat.HEX);
+
+			// Default to PG INT_MAX number of attempts
+			const maxAttemptCount = req.maxAttempts ?? 0x7FFFFFFF;
+
+			// If expiry is left unspecified, set for 1 day from now
+			const expireAt = req.expireAt ? new Date(req.expireAt) : new Date(Date.now() + 24 * 60 * 60 * 1000);
+
+			const [verification] = await ctx.db.insert(Database.verifications).values({
+				// The identifying data for the insertion. Not necessarily unique.
+				data: req.data,
+
+				code,
+				token,
+				maxAttemptCount,
+				expireAt,
+			}).returning({
+				id: Database.verifications.id,
+				code: Database.verifications.code,
+				token: Database.verifications.token,
+			}).onConflictDoNothing({
+				target: Database.verifications.code,
+			});
+
+			if (!verification) {
+				failedCodes.push(code);
+				continue;
+			}
+			return verification;
+		}
+
+		throw new RuntimeError("unable_to_generate_unique_code");
+	} catch (e) {
+		if (e instanceof RuntimeError) {
+			throw e;
+		} else if (e instanceof Query.DrizzleError) {
+			throw new RuntimeError("failed_to_create");
+		} else {
+			throw new RuntimeError("unknown_err");
+		}
+	} finally {
+		await Promise.all(failedCodes.map(code => moveToOldIfNecessary(ctx, code)));
+	}
+}

modules/verifications/scripts/get.ts

@@ -0,0 +1,39 @@
+import { ScriptContext, Query, Database, RuntimeError, UnreachableError } from "../module.gen.ts";
+import { Verification } from "../utils/migrate.ts";
+
+interface IdRequest {
+	id: string;
+}
+interface TokenRequest {
+	token: string;
+}
+interface DataRequest {
+	data: {};
+}
+
+export type Request = IdRequest | TokenRequest | DataRequest;
+
+export interface Response {
+	verification?: Verification;
+}
+
+export async function run(ctx: ScriptContext, req: Request): Promise<Response> {
+	let where: Query.SQL;
+	if ("id" in req) {
+		where = Query.eq(Database.verifications.id, req.id);
+	} else if ("token" in req) {
+		where = Query.eq(Database.verifications.token, req.token);
+	} else if ("data" in req) {
+		where = Query.eq(Database.verifications.data, req.data);
+	} else {
+		throw new UnreachableError(req);
+	}
+	try {
+		const [verification] = await ctx.db.select()
+			.from(Database.verifications)
+			.where(where);
+		return { verification };
+	} catch (e) {
+		throw new RuntimeError("unknown_err");
+	}
+}

modules/verifications/scripts/invalidate.ts

@@ -0,0 +1,26 @@
+import { ScriptContext, Query, RuntimeError } from "../module.gen.ts";
+import { invalidate } from "../utils/migrate.ts";
+
+export interface Request {
+	token: string;
+}
+
+export interface Response {
+	data: unknown;
+}
+
+export async function run(ctx: ScriptContext, req: Request): Promise<Response> {
+	try {
+		const { data } = await invalidate(ctx, req.token);
+		
+		return { data };
+	} catch (e) {
+		if (e instanceof RuntimeError) {
+			throw e;
+		} else if (e instanceof Query.DrizzleError) {
+			throw new RuntimeError("failed_to_update");
+		} else {
+			throw new RuntimeError("unknown_err");
+		}
+	}
+}

modules/verifications/tests/e2e.ts

@@ -0,0 +1,86 @@
+import { test, TestContext, RuntimeError } from "../module.gen.ts";
+import { assert, assertEquals, assertRejects } from "https://deno.land/std@0.224.0/assert/mod.ts";
+import { faker } from "https://deno.land/x/deno_faker@v1.0.3/mod.ts";
+
+test("right_code_first_time", async (ctx: TestContext) => {
+	const data = { email: faker.internet.email() };
+	const createdVerification = await ctx.modules.verifications.create({ data });
+	const attemptResult = await ctx.modules.verifications.attempt({
+		token: createdVerification.token,
+		code: createdVerification.code,
+	});
+
+	assert(attemptResult.succeeded);
+	assert(!attemptResult.canTryAgain);
+	assertEquals(attemptResult.data, data);
+});
+
+test("wrong_code_fail", async (ctx: TestContext) => {
+	const data = { email: faker.internet.email() };
+
+	const createdVerification = await ctx.modules.verifications.create({ data });
+	const attemptResult = await ctx.modules.verifications.attempt({
+		token: createdVerification.token,
+		code: "AAAAAAAA",
+	});
+
+	assert(!attemptResult.succeeded, "Verification succeeded when it shouldn't have");
+	assert(attemptResult.canTryAgain, "Verification should have more than 1 try");
+	assertEquals(attemptResult.data, data, "Verification data did not match");
+});
+
+test("overattempted", async (ctx: TestContext) => {
+	const data = { email: faker.internet.email() };
+
+	const MAX_ATTEMPTS = 5;
+
+	const createdVerification = await ctx.modules.verifications.create({
+		data,
+		maxAttempts: MAX_ATTEMPTS,
+	});
+
+	for (let i = 0; i < MAX_ATTEMPTS - 1; i++) {
+		const attemptResult = await ctx.modules.verifications.attempt({
+			token: createdVerification.token,
+			code: "AAAAAAAA",
+		});
+
+		assert(!attemptResult.succeeded, "Verification succeeded when it shouldn't have");
+		assert(attemptResult.canTryAgain, "Verification ran out of tries earlier than it should have");
+		assertEquals(attemptResult.data, data, "Verification data did not match");
+	}
+
+	const attemptResult = await ctx.modules.verifications.attempt({
+		token: createdVerification.token,
+		code: "AAAAAAAA",
+	});
+	assert(!attemptResult.succeeded, "Verification succeeded when it shouldn't have");
+	assert(!attemptResult.canTryAgain, "Verification should be out of tries");
+	assertEquals(attemptResult.data, data, "Verification data did not match");
+
+
+	const err = await assertRejects(() => ctx.modules.verifications.attempt({
+		token: createdVerification.token,
+		code: "AAAAAAAA",
+	}), RuntimeError);
+
+	assertEquals(err.code, "no_verification_found");
+});
+
+test("get_all_methods", async (ctx: TestContext) => {
+	const data = { email: faker.internet.email() };
+
+	const createdVerification = await ctx.modules.verifications.create({ data });
+	const getById = await ctx.modules.verifications.get({
+		id: createdVerification.id,
+	});
+	const getByToken = await ctx.modules.verifications.get({
+		token: createdVerification.token,
+	});
+	const getByData = await ctx.modules.verifications.get({
+		data,
+	});
+
+	assertEquals(getById, getByToken);
+	assertEquals(getByToken, getByData);
+});