sveltekit-auth-example 5.6.0 → 5.6.1

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 - Add password complexity checking on /register and /profile pages (only checks for length currently despite what the pages say)
 
+# 5.6.1
+
+- Add JSDoc comments throughout the codebase (`app.d.ts`, server hooks, route handlers, lib utilities, Svelte components)
+
 # 5.6.0
 
 - Split `db_create.sql` into `db_create.sql` (role + database creation) and `db_schema.sql` (schema, functions, seed data)

package/db_create.sql

@@ -1,5 +1,6 @@
 -- Run via db_create.sh or:
 -- $ psql -d postgres -f db_create.sql && psql -d auth -f db_schema.sql
+
 -- Create role if not already there
 DO $do$
 BEGIN
@@ -32,367 +33,3 @@ LIMIT
 	= -1;
 
 COMMENT ON DATABASE auth IS 'SvelteKit Auth Example';
-
--- 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.6.0",
+	"version": "5.6.1",
 	"author": "Nate Stuyvesant",
 	"license": "https://github.com/nstuyvesant/sveltekit-auth-example/blob/master/LICENSE",
 	"repository": {
@@ -29,6 +29,7 @@
 		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
 		"lint": "prettier --check . && eslint .",
 		"format": "prettier --write .",
+		"coverage": "vitest run --coverage",
 		"test:e2e": "playwright test",
 		"test:unit": "vitest"
 	},

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
+/** 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,7 +36,7 @@ function checkRateLimit(ip: string): boolean {
 	return true
 }
 
-// Periodically clean up expired entries to prevent unbounded memory growth
+/** Periodically removes expired entries from {@link ipRateLimit} to prevent unbounded memory growth. */
 setInterval(
 	() => {
 		const now = Date.now()
@@ -32,7 +47,15 @@ setInterval(
 	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)',
@@ -42,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/mfa-code.ts

@@ -1,6 +1,12 @@
 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 },

package/src/lib/server/email/password-reset.ts

@@ -1,6 +1,12 @@
 import { DOMAIN, SENDGRID_SENDER } from '$env/static/private'
 import { sendMessage } from '$lib/server/sendgrid'
 
+/**
+ * Sends a password reset email containing a link with a one-time reset token.
+ *
+ * @param toEmail - The recipient's email address.
+ * @param token - The password reset token to embed in the reset link.
+ */
 export const sendPasswordResetEmail = async (toEmail: string, token: string) => {
 	await sendMessage({
 		to: { email: toEmail },