sveltekit-auth-example 5.5.0 → 5.6.1

package/db_schema.sql

@@ -0,0 +1,369 @@
+-- Run via db_create.sh or:
+-- $ psql -d auth -f db_schema.sql
+-- Required for password hashing
+CREATE EXTENSION IF NOT EXISTS pgcrypto;
+
+-- Required to generate UUIDs for sessions
+CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+
+-- Required for case-insensitive text (email_address domain)
+CREATE EXTENSION IF NOT EXISTS citext;
+
+-- Using hard-coded roles (often this would be a table)
+CREATE TYPE public.roles AS ENUM('student', 'teacher', 'admin');
+
+ALTER TYPE public.roles OWNER TO auth;
+
+-- Domains
+CREATE DOMAIN public.email_address AS citext CHECK (
+	length(VALUE) <= 254
+	AND VALUE = btrim(VALUE)
+	AND VALUE ~* '^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$'
+);
+
+COMMENT ON DOMAIN public.email_address IS 'RFC-compliant email address (case-insensitive, max 254 chars)';
+
+CREATE DOMAIN public.persons_name AS text CHECK (length(VALUE) <= 20) NOT NULL;
+
+COMMENT ON DOMAIN public.persons_name IS 'Person first or last name (max 20 characters)';
+
+CREATE DOMAIN public.phone_number AS text CHECK (
+	VALUE IS NULL
+	OR length(VALUE) <= 50
+);
+
+COMMENT ON DOMAIN public.phone_number IS 'Phone number (max 50 characters)';
+
+CREATE TABLE IF NOT EXISTS public.users (
+	id integer NOT NULL GENERATED ALWAYS AS IDENTITY (
+		INCREMENT 1 START 1 MINVALUE 1 MAXVALUE 2147483647 CACHE 1
+	),
+	role roles NOT NULL DEFAULT 'student'::roles,
+	email email_address NOT NULL,
+	password character varying(80) COLLATE pg_catalog."default",
+	first_name persons_name,
+	last_name persons_name,
+	opt_out boolean NOT NULL DEFAULT false,
+	email_verified boolean NOT NULL DEFAULT false,
+	phone phone_number,
+	CONSTRAINT users_pkey PRIMARY KEY (id),
+	CONSTRAINT users_email_unique UNIQUE (email)
+) TABLESPACE pg_default;
+
+ALTER TABLE public.users OWNER TO auth;
+
+CREATE INDEX users_first_name_index ON public.users USING btree (
+	first_name COLLATE pg_catalog."default" ASC NULLS LAST
+) TABLESPACE pg_default;
+
+CREATE INDEX users_last_name_index ON public.users USING btree (
+	last_name COLLATE pg_catalog."default" ASC NULLS LAST
+) TABLESPACE pg_default;
+
+CREATE INDEX users_password ON public.users USING btree (
+	password COLLATE pg_catalog."default" ASC NULLS LAST
+) TABLESPACE pg_default;
+
+CREATE TABLE IF NOT EXISTS public.sessions (
+	id uuid NOT NULL DEFAULT uuid_generate_v4 (),
+	user_id integer NOT NULL,
+	expires timestamptz NOT NULL DEFAULT (CURRENT_TIMESTAMP + INTERVAL '2 hours'),
+	CONSTRAINT sessions_pkey PRIMARY KEY (id),
+	CONSTRAINT sessions_user_fkey FOREIGN KEY (user_id) REFERENCES public.users (id) MATCH SIMPLE ON UPDATE CASCADE ON DELETE CASCADE,
+	CONSTRAINT sessions_one_per_user UNIQUE (user_id)
+) TABLESPACE pg_default;
+
+ALTER TABLE public.sessions OWNER TO auth;
+
+CREATE OR REPLACE FUNCTION public.authenticate (input json, OUT response json) RETURNS json LANGUAGE 'plpgsql' COST 100 VOLATILE PARALLEL UNSAFE AS $BODY$
+DECLARE
+  input_email text := trim(input->>'email');
+  input_password text := input->>'password';
+  v_user users%ROWTYPE;
+BEGIN
+  IF input_email IS NULL OR input_password IS NULL THEN
+    response := json_build_object('statusCode', 400, 'status', 'Please provide an email address and password to authenticate.', 'user', NULL, 'sessionId', NULL);
+    RETURN;
+  END IF;
+
+  SELECT * INTO v_user FROM users
+  WHERE email = input_email AND password = crypt(input_password, password) LIMIT 1;
+
+  IF NOT FOUND THEN
+    response := json_build_object('statusCode', 401, 'status', 'Invalid username/password combination.', 'user', NULL, 'sessionId', NULL);
+  ELSIF NOT v_user.email_verified THEN
+    response := json_build_object('statusCode', 403, 'status', 'Please verify your email address before logging in.', 'user', NULL, 'sessionId', NULL);
+  ELSE
+    response := json_build_object(
+      'statusCode', 200,
+      'status', 'Login successful.',
+      'user', json_build_object('id', v_user.id, 'role', v_user.role, 'email', input_email, 'firstName', v_user.first_name, 'lastName', v_user.last_name, 'phone', v_user.phone, 'optOut', v_user.opt_out),
+      'sessionId', create_session(v_user.id)
+    );
+  END IF;
+END;
+$BODY$;
+
+ALTER FUNCTION public.authenticate (json) OWNER TO auth;
+
+CREATE OR REPLACE FUNCTION public.create_session (input_user_id integer) RETURNS uuid LANGUAGE 'sql' COST 100 VOLATILE PARALLEL UNSAFE AS $BODY$
+  -- Remove expired sessions (index-friendly cleanup)
+  DELETE FROM sessions WHERE expires < CURRENT_TIMESTAMP;
+  -- Remove any existing session(s) for this user
+  DELETE FROM sessions WHERE user_id = input_user_id;
+  -- Create the new session
+  INSERT INTO sessions(user_id) VALUES (input_user_id) RETURNING sessions.id;
+$BODY$;
+
+ALTER FUNCTION public.create_session (integer) OWNER TO auth;
+
+CREATE OR REPLACE FUNCTION public.get_session (input_session_id uuid) RETURNS json LANGUAGE 'sql' AS $BODY$
+SELECT json_build_object(
+  'id', sessions.user_id,
+  'role', users.role,
+  'email', users.email,
+  'firstName', users.first_name,
+  'lastName', users.last_name,
+  'phone', users.phone,
+  'optOut', users.opt_out,
+  'expires', sessions.expires
+) AS user
+FROM sessions
+  INNER JOIN users ON sessions.user_id = users.id
+WHERE sessions.id = input_session_id AND expires > CURRENT_TIMESTAMP LIMIT 1;
+$BODY$;
+
+ALTER FUNCTION public.get_session (uuid) OWNER TO auth;
+
+-- Like get_session but also bumps the expiry (sliding sessions).
+-- Returns NULL if the session is expired or does not exist.
+CREATE OR REPLACE FUNCTION public.get_and_update_session (input_session_id uuid) RETURNS json LANGUAGE 'plpgsql' AS $BODY$
+DECLARE
+  result json;
+BEGIN
+  UPDATE sessions
+    SET expires = CURRENT_TIMESTAMP + INTERVAL '2 hours'
+  WHERE id = input_session_id AND expires > CURRENT_TIMESTAMP;
+
+  IF NOT FOUND THEN
+    RETURN NULL;
+  END IF;
+
+  SELECT json_build_object(
+    'id', sessions.user_id,
+    'role', users.role,
+    'email', users.email,
+    'firstName', users.first_name,
+    'lastName', users.last_name,
+    'phone', users.phone,
+    'optOut', users.opt_out,
+    'expires', sessions.expires
+  ) INTO result
+  FROM sessions
+    INNER JOIN users ON sessions.user_id = users.id
+  WHERE sessions.id = input_session_id;
+
+  RETURN result;
+END;
+$BODY$;
+
+ALTER FUNCTION public.get_and_update_session (uuid) OWNER TO auth;
+
+CREATE OR REPLACE FUNCTION public.verify_email_and_create_session (input_id integer) RETURNS uuid LANGUAGE 'plpgsql' COST 100 VOLATILE PARALLEL UNSAFE AS $BODY$
+DECLARE
+  session_id uuid;
+BEGIN
+  UPDATE users SET email_verified = true WHERE id = input_id;
+  SELECT create_session(input_id) INTO session_id;
+  RETURN session_id;
+END;
+$BODY$;
+
+ALTER FUNCTION public.verify_email_and_create_session (integer) OWNER TO auth;
+
+CREATE OR REPLACE FUNCTION public.register (input json, OUT user_session json) RETURNS json LANGUAGE 'plpgsql' COST 100 VOLATILE PARALLEL UNSAFE AS $BODY$
+DECLARE
+  input_email text := trim(input->>'email');
+  input_first_name text := trim(input->>'firstName');
+  input_last_name text := trim(input->>'lastName');
+  input_phone text := trim(input->>'phone');
+  input_password text := input->>'password';
+BEGIN
+  PERFORM id FROM users WHERE email = input_email;
+  IF NOT FOUND THEN
+    INSERT INTO users(role, password, email, first_name, last_name, phone)
+      VALUES('student', crypt(input_password, gen_salt('bf', 12)), input_email, input_first_name, input_last_name, input_phone)
+      RETURNING
+        json_build_object(
+          'sessionId', create_session(users.id),
+          'user', json_build_object('id', users.id, 'role', 'student', 'email', input_email, 'firstName', input_first_name, 'lastName', input_last_name, 'phone', input_phone, 'optOut', users.opt_out)
+        ) INTO user_session;
+  ELSE -- user is registering account that already exists so set sessionId and user to null so client can let them know
+    SELECT authenticate(input) INTO user_session;
+  END IF;
+END;
+$BODY$;
+
+ALTER FUNCTION public.register (json) OWNER TO auth;
+
+CREATE OR REPLACE FUNCTION public.start_gmail_user_session (input json, OUT user_session json) RETURNS json LANGUAGE 'plpgsql' COST 100 VOLATILE PARALLEL UNSAFE AS $BODY$
+DECLARE
+  input_email varchar(80) := LOWER(TRIM((input->>'email')::varchar));
+  input_first_name varchar(20) := TRIM((input->>'firstName')::varchar);
+  input_last_name varchar(20) := TRIM((input->>'lastName')::varchar);
+BEGIN
+  -- Google verifies email ownership; mark user as verified on every sign-in
+  UPDATE users SET email_verified = true WHERE email = input_email;
+  SELECT json_build_object('id', create_session(users.id), 'user', json_build_object('id', users.id, 'role', users.role, 'email', input_email, 'firstName', users.first_name, 'lastName', users.last_name, 'phone', users.phone)) INTO user_session FROM users WHERE email = input_email;
+  IF NOT FOUND THEN
+    INSERT INTO users(role, email, first_name, last_name, email_verified)
+      VALUES('student', input_email, input_first_name, input_last_name, true)
+      RETURNING
+        json_build_object(
+          'id', create_session(users.id),
+          'user', json_build_object('id', users.id, 'role', 'student', 'email', input_email, 'firstName', input_first_name, 'lastName', input_last_name, 'phone', null)
+        ) INTO user_session;
+  END IF;
+END;
+$BODY$;
+
+ALTER FUNCTION public.start_gmail_user_session (json) OWNER TO auth;
+
+CREATE PROCEDURE public.delete_session (input_id integer) LANGUAGE sql AS $$
+DELETE FROM sessions WHERE user_id = input_id;
+$$;
+
+CREATE OR REPLACE PROCEDURE public.delete_user (input_id integer) LANGUAGE sql AS $$
+DELETE FROM users WHERE id = input_id;
+$$;
+
+ALTER PROCEDURE public.delete_user (integer) OWNER TO auth;
+
+CREATE OR REPLACE PROCEDURE public.reset_password (IN input_id integer, IN input_password text) LANGUAGE plpgsql AS $procedure$
+BEGIN
+  UPDATE users SET password = crypt(input_password, gen_salt('bf', 12)) WHERE id = input_id;
+END;
+$procedure$;
+
+ALTER PROCEDURE public.reset_password (integer, text) OWNER TO auth;
+
+CREATE OR REPLACE PROCEDURE public.upsert_user (input json) LANGUAGE plpgsql AS $BODY$
+DECLARE
+  input_id integer := COALESCE((input->>'id')::integer, 0);
+  input_role roles := COALESCE((input->>'role')::roles, 'student');
+  input_email varchar(80) := LOWER(TRIM((input->>'email')::varchar));
+  input_password varchar(80) := COALESCE((input->>'password')::varchar, '');
+  input_first_name varchar(20) := TRIM((input->>'firstName')::varchar);
+  input_last_name varchar(20) := TRIM((input->>'lastName')::varchar);
+  input_phone varchar(23) := TRIM((input->>'phone')::varchar);
+BEGIN
+  IF input_id = 0 THEN
+    INSERT INTO users (role, email, password, first_name, last_name, phone, email_verified)
+    VALUES (
+      input_role, input_email, crypt(input_password, gen_salt('bf', 12)),
+      input_first_name, input_last_name, input_phone, true
+    );
+  ELSE
+    UPDATE users SET
+      role = input_role,
+      email = input_email,
+      email_verified = true,
+      password = CASE WHEN input_password = ''
+        THEN password -- leave as is (we are updating fields other than the password)
+        ELSE crypt(input_password, gen_salt('bf', 12))
+      END,
+      first_name = input_first_name,
+      last_name = input_last_name,
+      phone = input_phone
+    WHERE id = input_id;
+  END IF;
+END;
+$BODY$;
+
+ALTER PROCEDURE public.upsert_user (json) OWNER TO auth;
+
+CREATE OR REPLACE PROCEDURE public.update_user (input_id integer, input json) LANGUAGE plpgsql AS $BODY$
+DECLARE
+  input_email varchar(80) := LOWER(TRIM((input->>'email')::varchar));
+  input_password varchar(80) := COALESCE((input->>'password')::varchar, '');
+  input_first_name varchar(20) := TRIM((input->>'firstName')::varchar);
+  input_last_name varchar(20) := TRIM((input->>'lastName')::varchar);
+  input_phone varchar(23) := TRIM((input->>'phone')::varchar);
+BEGIN
+  UPDATE users SET
+    email = input_email,
+    password = CASE WHEN input_password = ''
+      THEN password -- leave as is (we are updating fields other than the password)
+      ELSE crypt(input_password, gen_salt('bf', 12))
+    END,
+    first_name = input_first_name,
+    last_name = input_last_name,
+    phone = input_phone
+  WHERE id = input_id;
+END;
+$BODY$;
+
+ALTER PROCEDURE public.update_user (integer, json) OWNER TO auth;
+
+-- MFA codes table (one pending code per user, replaced on each new login attempt)
+CREATE TABLE IF NOT EXISTS public.mfa_codes (
+	user_id integer NOT NULL,
+	code varchar(6) NOT NULL,
+	expires timestamptz NOT NULL DEFAULT (CURRENT_TIMESTAMP + INTERVAL '10 minutes'),
+	CONSTRAINT mfa_codes_pkey PRIMARY KEY (user_id),
+	CONSTRAINT mfa_codes_user_fkey FOREIGN KEY (user_id) REFERENCES public.users (id) ON DELETE CASCADE
+) TABLESPACE pg_default;
+
+ALTER TABLE public.mfa_codes OWNER TO auth;
+
+-- Generate and store a fresh 6-digit MFA code for a user, returning the code
+CREATE OR REPLACE FUNCTION public.create_mfa_code (input_user_id integer) RETURNS varchar LANGUAGE plpgsql AS $BODY$
+DECLARE
+  v_code varchar(6) := lpad(floor(random() * 1000000)::integer::text, 6, '0');
+BEGIN
+  DELETE FROM mfa_codes WHERE expires < CURRENT_TIMESTAMP;
+  INSERT INTO mfa_codes(user_id, code)
+  VALUES (input_user_id, v_code)
+  ON CONFLICT (user_id) DO UPDATE
+    SET code = EXCLUDED.code,
+        expires = CURRENT_TIMESTAMP + INTERVAL '10 minutes';
+  RETURN v_code;
+END;
+$BODY$;
+
+ALTER FUNCTION public.create_mfa_code (integer) OWNER TO auth;
+
+-- Verify an MFA code for a given email address.
+-- Returns the user_id on success (and deletes the code), or NULL on failure.
+CREATE OR REPLACE FUNCTION public.verify_mfa_code (input_email text, input_code text) RETURNS integer LANGUAGE plpgsql AS $BODY$
+DECLARE
+  v_user_id integer;
+BEGIN
+  SELECT mfa_codes.user_id INTO v_user_id
+  FROM mfa_codes
+    INNER JOIN users ON mfa_codes.user_id = users.id
+  WHERE users.email = input_email
+    AND mfa_codes.code = input_code
+    AND mfa_codes.expires > CURRENT_TIMESTAMP;
+
+  IF FOUND THEN
+    DELETE FROM mfa_codes WHERE user_id = v_user_id;
+  END IF;
+
+  RETURN v_user_id;
+END;
+$BODY$;
+
+ALTER FUNCTION public.verify_mfa_code (text, text) OWNER TO auth;
+
+CALL public.upsert_user (
+	'{"id":0, "role":"admin", "email":"admin@example.com", "password":"admin123", "firstName":"Jane", "lastName":"Doe", "phone":"412-555-1212"}'::json
+);
+
+CALL public.upsert_user (
+	'{"id":0, "role":"teacher", "email":"teacher@example.com", "password":"teacher123", "firstName":"John", "lastName":"Doe", "phone":"724-555-1212"}'::json
+);
+
+CALL public.upsert_user (
+	'{"id":0, "role":"student", "email":"student@example.com", "password":"student123", "firstName":"Justin", "lastName":"Case", "phone":"814-555-1212"}'::json
+);

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "sveltekit-auth-example",
 	"description": "SvelteKit Authentication Example",
-	"version": "5.5.0",
+	"version": "5.6.1",
 	"author": "Nate Stuyvesant",
 	"license": "https://github.com/nstuyvesant/sveltekit-auth-example/blob/master/LICENSE",
 	"repository": {
@@ -28,7 +28,10 @@
 		"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
 		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
 		"lint": "prettier --check . && eslint .",
-		"format": "prettier --write ."
+		"format": "prettier --write .",
+		"coverage": "vitest run --coverage",
+		"test:e2e": "playwright test",
+		"test:unit": "vitest"
 	},
 	"engines": {
 		"node": "^24.14.0"

package/src/app.d.ts

@@ -4,42 +4,60 @@
 // for information about these interfaces
 // and what to do when importing types
 declare namespace App {
+	/** Per-request server-side locals populated by `hooks.server.ts`. */
 	interface Locals {
+		/** The authenticated user, or `undefined` when no valid session exists. */
 		user: User | undefined
 	}
 
 	// interface Platform {}
 
+	/** Private environment variables (server-side only). */
 	interface PrivateEnv {
 		// $env/static/private
+		/** PostgreSQL connection string. */
 		DATABASE_URL: string
+		/** Public-facing domain used to construct email links (e.g. `https://example.com`). */
 		DOMAIN: string
+		/** Secret key used to sign and verify JWTs. */
 		JWT_SECRET: string
+		/** SendGrid API key. */
 		SENDGRID_KEY: string
+		/** Default sender email address for outgoing mail. */
 		SENDGRID_SENDER: string
 	}
 
+	/** Public environment variables (safe to expose to the client). */
 	interface PublicEnv {
 		// $env/static/public
+		/** Google OAuth 2.0 client ID for Google Sign-In. */
 		PUBLIC_GOOGLE_CLIENT_ID: string
 	}
 }
 
+/** Result returned by the `authenticate` and `register` SQL functions. */
 interface AuthenticationResult {
+	/** HTTP status code to use when the operation fails. */
 	statusCode: NumericRange<400, 599>
+	/** Human-readable status message. */
 	status: string
+	/** The authenticated or registered user, if successful. */
 	user: User
+	/** The newly created session ID. */
 	sessionId: string
 }
 
+/** Raw login credentials submitted by the user. */
 interface Credentials {
 	email: string
 	password: string
 }
 
+/** Persistent properties stored in the database for a user account. */
 interface UserProperties {
 	id: number
-	expires?: string // ISO-8601 datetime
+	/** ISO-8601 datetime at which the current session expires. */
+	expires?: string
 	role: 'student' | 'teacher' | 'admin'
 	password?: string
 	firstName?: string
@@ -48,9 +66,12 @@ interface UserProperties {
 	phone?: string
 }
 
+/** A user record, or `undefined`/`null` when unauthenticated. */
 type User = UserProperties | undefined | null
 
+/** A database session paired with its associated user. */
 interface UserSession {
+	/** UUID session identifier stored in the `session` cookie. */
 	id: string
 	user: User
 }

package/src/hooks.server.ts

@@ -2,13 +2,28 @@ import type { Handle, RequestEvent } from '@sveltejs/kit'
 import { error } from '@sveltejs/kit'
 import { query } from '$lib/server/db'
 
-// In-memory IP-based rate limiter for sensitive auth endpoints.
-// For multi-instance deployments, replace with a shared store like Redis.
+/**
+ * In-memory IP-based rate limiter for sensitive auth endpoints.
+ * @remarks For multi-instance deployments, replace with a shared store like Redis.
+ */
 const ipRateLimit = new Map<string, { count: number; resetAt: number }>()
+/** Duration of each rate-limit window in milliseconds (15 minutes). */
 const RATE_LIMIT_WINDOW_MS = 15 * 60 * 1000 // 15 minutes
+/** Maximum number of requests allowed per IP within {@link RATE_LIMIT_WINDOW_MS}. */
 const RATE_LIMIT_MAX_REQUESTS = 20
-const RATE_LIMITED_PATHS = new Set(['/auth/login', '/auth/register', '/auth/forgot'])
+/** Set of path prefixes that are subject to IP-based rate limiting. */
+const RATE_LIMITED_PATHS = new Set(['/auth/login', '/auth/register', '/auth/forgot', '/auth/mfa'])
 
+/**
+ * Checks whether the given IP address is within its rate-limit allowance.
+ *
+ * Starts a new window if none exists or the previous one has expired. Once
+ * {@link RATE_LIMIT_MAX_REQUESTS} is reached within the window, subsequent
+ * calls return `false` until the window resets.
+ *
+ * @param ip - The client IP address to check.
+ * @returns `true` if the request is allowed, `false` if the limit is exceeded.
+ */
 function checkRateLimit(ip: string): boolean {
 	const now = Date.now()
 	const entry = ipRateLimit.get(ip)
@@ -21,15 +36,26 @@ function checkRateLimit(ip: string): boolean {
 	return true
 }
 
-// Periodically clean up expired entries to prevent unbounded memory growth
-setInterval(() => {
-	const now = Date.now()
-	for (const [key, value] of ipRateLimit) {
-		if (now > value.resetAt) ipRateLimit.delete(key)
-	}
-}, 60 * 60 * 1000)
+/** Periodically removes expired entries from {@link ipRateLimit} to prevent unbounded memory growth. */
+setInterval(
+	() => {
+		const now = Date.now()
+		for (const [key, value] of ipRateLimit) {
+			if (now > value.resetAt) ipRateLimit.delete(key)
+		}
+	},
+	60 * 60 * 1000
+)
 
-// Attach authorization to each server request (role may have changed)
+/**
+ * Looks up the session in the database and attaches the associated user to
+ * `event.locals`. Also updates the session's last-active timestamp.
+ *
+ * Sets `event.locals.user` to `undefined` if the session is not found.
+ *
+ * @param sessionId - The session UUID read from the request cookie.
+ * @param event - The SvelteKit request event to attach the user to.
+ */
 async function attachUserToRequestEvent(sessionId: string, event: RequestEvent) {
 	const result = await query(
 		'SELECT get_and_update_session($1::uuid)',
@@ -39,7 +65,16 @@ async function attachUserToRequestEvent(sessionId: string, event: RequestEvent)
 	event.locals.user = result.rows[0]?.get_and_update_session // undefined if not found
 }
 
-// Invoked for each endpoint called and initially for SSR router
+/**
+ * SvelteKit server hook — invoked for every request before the endpoint or
+ * page load function runs.
+ *
+ * Responsibilities:
+ * - Short-circuits static asset requests (`/_app/`) immediately.
+ * - Enforces IP-based rate limiting on sensitive auth paths.
+ * - Resolves the session cookie to a user and populates `event.locals.user`.
+ * - Deletes a stale session cookie when no matching session is found.
+ */
 export const handle = (async ({ event, resolve }) => {
 	const { cookies, url } = event
 

package/src/lib/app-state.svelte.ts

@@ -1,9 +1,17 @@
+/** Represents a toast notification shown to the user. */
 interface Toast {
+	/** Short heading displayed at the top of the toast. */
 	title: string
+	/** Main message content of the toast. */
 	body: string
+	/** Whether the toast is currently visible. */
 	isOpen: boolean
 }
 
+/**
+ * Reactive singleton holding global application state.
+ * Access via the exported {@link appState} instance.
+ */
 class AppState {
 	/** Currently logged-in user, undefined when not authenticated */
 	user = $state<User | undefined>(undefined)

package/src/lib/auth-redirect.ts

@@ -4,6 +4,10 @@ import { page } from '$app/state'
 /**
  * Redirect the user to the appropriate page after a successful login,
  * respecting an optional ?referrer= query parameter.
+ *
+ * @param user - The authenticated user. Redirects to a role-based default route
+ * (`/teachers`, `/admin`, or `/`) unless a valid same-origin `referrer` query
+ * parameter is present, in which case that path is used instead.
  */
 export function redirectAfterLogin(user: User): void {
 	if (!user) return

package/src/lib/focus.ts

@@ -1,3 +1,11 @@
+/**
+ * Focuses the first invalid input element within a form.
+ *
+ * Iterates through the form's elements in DOM order and calls `focus()` on the
+ * first `HTMLInputElement` that fails constraint validation, then stops.
+ *
+ * @param form - The form element to search for invalid inputs.
+ */
 export const focusOnFirstError = (form: HTMLFormElement) => {
 	for (const field of form.elements) {
 		if (field instanceof HTMLInputElement && !field.checkValidity()) {

package/src/lib/google.ts

@@ -2,6 +2,13 @@ import { PUBLIC_GOOGLE_CLIENT_ID } from '$env/static/public'
 import { appState } from '$lib/app-state.svelte'
 import { redirectAfterLogin } from '$lib/auth-redirect'
 
+/**
+ * Renders the Google Sign-In button inside the element with id `googleButton`.
+ *
+ * Reads the element's width (falling back to its parent's width, then 400px)
+ * and passes it to the Google Identity Services SDK so the button scales
+ * correctly within its container.
+ */
 export function renderGoogleButton() {
 	const btn = document.getElementById('googleButton')
 	if (btn) {
@@ -15,6 +22,16 @@ export function renderGoogleButton() {
 	}
 }
 
+/**
+ * Initializes the Google Identity Services SDK (once per session) and
+ * registers a callback that handles the credential response after the user
+ * signs in with Google.
+ *
+ * On a successful sign-in the callback:
+ * 1. POSTs the Google credential token to `/auth/google`.
+ * 2. Updates {@link appState.user} with the returned user.
+ * 3. Redirects the user via {@link redirectAfterLogin}.
+ */
 export function initializeGoogleAccounts() {
 	if (!appState.googleInitialized) {
 		google.accounts.id.initialize({

package/src/lib/server/db.ts

@@ -30,6 +30,15 @@ pool.on('error', (err: Error) => {
 	console.error('Unexpected error on idle client', err)
 })
 
+/**
+ * Executes a parameterized SQL query using the connection pool.
+ *
+ * @template T - The expected row type, extending QueryResultRow.
+ * @param sql - The SQL query string with optional $1, $2, ... placeholders.
+ * @param params - Optional positional parameter values to bind to the query.
+ * @param name - Optional name for the query to use a prepared statement.
+ * @returns A promise resolving to the typed QueryResult.
+ */
 queryFn = <T extends QueryResultRow>(
 	sql: string,
 	params?: (string | number | boolean | object | null)[],

package/src/lib/server/email/index.ts

@@ -1,2 +1,3 @@
 export { sendPasswordResetEmail } from './password-reset'
 export { sendVerificationEmail } from './verify-email'
+export { sendMfaCodeEmail } from './mfa-code'

package/src/lib/server/email/mfa-code.ts

@@ -0,0 +1,22 @@
+import { SENDGRID_SENDER } from '$env/static/private'
+import { sendMessage } from '$lib/server/sendgrid'
+
+/**
+ * Sends a multi-factor authentication (MFA) verification code email to the user.
+ *
+ * @param toEmail - The recipient's email address.
+ * @param code - The one-time verification code to include in the email.
+ */
+export const sendMfaCodeEmail = async (toEmail: string, code: string) => {
+	await sendMessage({
+		to: { email: toEmail },
+		from: SENDGRID_SENDER,
+		subject: 'Your login verification code',
+		categories: ['account'],
+		html: `
+      <p>Your verification code is:</p>
+      <p style="font-size: 2em; font-weight: bold; letter-spacing: 0.25em;">${code}</p>
+      <p>This code expires in 10 minutes. If you did not attempt to log in, you can safely ignore this email.</p>
+    `
+	})
+}