docs: add basic doc comments for SIWE authentication flow [skip ci]

Author: AryanGodara

apps/leaderboard-backend/src/auth/challengeGenerator.ts

@@ -1,3 +1,17 @@
+/**
+ * Authentication Challenge Generator
+ *
+ * This module handles the creation of EIP-4361 (Sign-In with Ethereum) compliant
+ * authentication challenges using Viem's SIWE utilities.
+ *
+ * The flow is as follows:
+ * 1. Client requests a challenge with their wallet address
+ * 2. Server generates a challenge message using createSiweMessage
+ * 3. Server stores the challenge in the database
+ * 4. Client signs the message with their wallet
+ * 5. Client sends the signature back for verification
+ */
+
 import type { Address, Hex } from "@happy.tech/common"
 import { hashMessage } from "viem"
 import { createSiweMessage, generateSiweNonce } from "viem/siwe"
@@ -36,9 +50,21 @@ export interface ChallengeMessage {
 }
 
 /**
- * Generates a secure challenge message for authentication
- * Following EIP-4361 (Sign-In with Ethereum) standard
- * Includes nonce and timestamps to prevent replay attacks
+ * Generates a secure challenge message for authentication following EIP-4361 (SIWE) standard
+ *
+ * This function creates a standardized message for wallet-based authentication that includes:
+ * - Domain and URI information to identify the application
+ * - Wallet address of the user attempting to authenticate
+ * - A cryptographically secure nonce to prevent replay attacks
+ * - Timestamps for issuance and expiration to limit the validity period
+ * - Optional resources that the user will be able to access
+ * - Optional request ID for tracking purposes
+ *
+ * The message is formatted according to the EIP-4361 standard using Viem's SIWE utilities.
+ * A hash of the message is also generated for database storage and verification.
+ *
+ * @param options Configuration options including wallet address and optional parameters
+ * @returns A challenge message object with all data needed for storage and verification
  */
 export function generateChallengeMessage(options: ChallengeMessageOptions): ChallengeMessage {
     const { walletAddress, requestId, resources } = options

apps/leaderboard-backend/src/auth/verifySignature.ts

@@ -1,3 +1,16 @@
+/**
+ * Signature Verification Module
+ *
+ * This module handles cryptographic verification of signatures against wallet addresses
+ * using the ERC-1271 standard for Smart Contract Accounts.
+ *
+ * The verification process works as follows:
+ * 1. The message is hashed to create a message hash
+ * 2. An RPC call is made to the wallet's isValidSignature method
+ * 3. The wallet implementation validates the signature according to ERC-1271
+ * 4. The result is interpreted as a boolean indicating validity
+ */
+
 import type { Address, Hex } from "@happy.tech/common"
 import { abis } from "@happy.tech/contracts/boop/anvil"
 import { http, createPublicClient, hashMessage } from "viem"
@@ -17,10 +30,10 @@ export const publicClient = createPublicClient({
  * Verifies a signature against a wallet address using ERC-1271 standard
  * Makes an RPC call to the smart contract account for signature verification
  *
- * @param walletAddress - The wallet address to verify against
- * @param message - The message that was signed
- * @param signature - The signature to verify
- * @returns Promise<boolean> - Whether the signature is valid
+ * @param walletAddress - The wallet address that allegedly signed the message
+ * @param message - The original message that was signed (plain text)
+ * @param signature - The signature produced by the wallet (hex string)
+ * @returns Promise<boolean> - True if the signature is valid, false otherwise
  */
 export async function verifySignature(walletAddress: Address, message: string, signature: Hex): Promise<boolean> {
     try {

apps/leaderboard-backend/src/repositories/AuthRepository.ts

@@ -175,8 +175,8 @@ export class AuthRepository {
     /**
      * Mark a challenge as used to prevent replay attacks
      * @param walletAddress The wallet address that requested the challenge
-     * @param message The message that was signed
-     * @returns True if the challenge was found and marked as used
+     * @param message The EIP-4361 compliant message that was signed
+     * @returns True if the challenge was found and marked as used, false otherwise
      */
     async markChallengeAsUsed(walletAddress: Address, message: string): Promise<boolean> {
         try {

apps/leaderboard-backend/src/routes/api/authRoutes.ts

@@ -14,13 +14,31 @@ import {
     AuthVerifyValidation,
 } from "../../validation/auth"
 
+/**
+ * The authentication flow consists of these main steps:
+ *
+ * 1. Challenge Generation (/auth/challenge):
+ *    - Client sends their wallet address
+ *    - Server creates a unique challenge message
+ *    - Server returns the message to be signed
+ *
+ * 2. Signature Verification (/auth/verify):
+ *    - Client signs the message and sends back signature
+ *    - Server validates message format using SIWE utilities
+ *    - Server checks database for valid challenge
+ *    - Server verifies signature on-chain
+ *    - Server creates session and returns token
+ *
+ * 3. Session Management:
+ *    - /auth/me - Get current user info
+ *    - /auth/sessions - List all active sessions
+ *    - /auth/logout - End the current session
+ */
+
 export default new Hono()
     /**
      * Request a challenge to sign
      * POST /auth/challenge
-     *
-     * Generates an EIP-4361 (Sign-In with Ethereum) compliant challenge message
-     * for the user to sign with their wallet.
      */
     .post("/challenge", AuthChallengeDescription, AuthChallengeValidation, async (c) => {
         try {