chore(docs): improve comments in code (#25)

* chore: document

* comment some more

* chore: some more comments

* chore: more comments

* chore: more comments

* chore: more comments

* chore: more comments

* chore: improve readme

Author: quirky-bluejay

.github/workflows/codeql-analysis.yml

@@ -9,6 +9,8 @@
 # the `language` matrix defined below to confirm you have the correct set of
 # supported CodeQL languages.
 #
+
+# This is for code quality scanning by github
 name: "CodeQL"
 
 on:

.github/workflows/deploy-image.yml

@@ -1,3 +1,6 @@
+# This action deploys and publishes a docker image to the github docker registry.
+# So that the image doesn't have to be built on deploy on the server.
+
 name: Create and publish a Docker image
 
 on:

.github/workflows/lint.yml

@@ -1,3 +1,5 @@
+# Auto run lint on push
+
 name: Lint
 on: push
 jobs:

README.md

@@ -2,4 +2,43 @@
 
 Backend service for [message.anothercat.me](https://message.anothercat.me)
 
-PRISMA_FIELD_ENCRYPTION_KEY: https://github.com/47ng/prisma-field-encryption#2-setup-your-encryption-key
+## Development
+
+### Prerequisites
+
+Node 17.5 (see .nvmrc)
+Postgresql 13 with user with write permissions
+Redis with REJSON
+
+### Setup
+
+Run `npm ci` to install directly from `package-lock.json` - if you use `npm install` or `npm i` instead it cannot be guaranteed that the dependencies work.
+
+Set up a `.env` file with the variables from `.env.example` and fill in the values.
+
+For PRISMA_FIELD_ENCRYPTION_KEY see: https://github.com/47ng/prisma-field-encryption#2-setup-your-encryption-key
+
+### Running
+
+Run `npm run dev` to start the development server.
+
+You will need to setup a tunnel or some kind of way to expose the server to discord. I use cloudflare tunnels. The endpoint for the discord interactions is `/interactions`
+
+You will need to have a gateway cache instance also running
+[see message-manager-discord/gateway](https://github.com/message-manager-discord/gateway) and [message-manager-discord/redis-discord-cache](https://github.com/message-manager-discord/redis-discord-cache)
+
+### Migrations
+
+Prisma is used for migrations - run `npm run migrate` to migrate the database.
+
+### General overview of important files
+
+.github/workflows - contains github actions for CI config
+prisma - contains prisma schema and migrations
+src - contains the source code
+.env - contains environment variables (do not use .env on production use docker env variables instead)
+.env.example - contains example environment variables
+.eslintrc.js - contains eslint config
+.prettierrc.json - contains prettier config
+.wakatime-project - contains wakatime config
+Dockerfile - contains docker config

package-lock.json

@@ -1,3 +1,4 @@
+// Database schema for postgresql database
 generator client {
   provider = "prisma-client-js"
 }
@@ -15,7 +16,6 @@ model Channel {
   guildId      BigInt
   guild        Guild     @relation(fields: [guildId], references: [id], onDelete: Cascade, onUpdate: NoAction)
   messages     Message[]
-
 }
 
 model Guild {
@@ -43,7 +43,6 @@ model Message {
 
   embed MessageEmbed?
 
-
   @@unique([id, editedAt])
 }
 

prisma/schema.prisma

@@ -1,4 +1,8 @@
-// This route file is separate from the other routes since auth routes are not versioned
+/**
+ * This route file is separate from the other routes since auth routes are not versioned
+ * As they are only used by the website - which is always up to date
+ * They are routes to run the OAuth2 flow with discord
+ */
 import { FastifyInstance } from "fastify";
 import httpErrors from "http-errors";
 const { Forbidden } = httpErrors;
@@ -8,13 +12,15 @@ import { v5 as uuidv5 } from "uuid";
 
 import DiscordOauthRequests from "./discordOauth";
 
+// Callback after authorized with discord
 const CallbackQuerystring = Type.Object({
   code: Type.String(),
   state: Type.Optional(Type.String()),
 });
 
 type CallbackQuerystringType = Static<typeof CallbackQuerystring>;
 
+// Route before authorized with discord - navigated too to get redirected to discord
 const AuthorizeQuerystring = Type.Object({
   redirect_to: Type.Optional(Type.String()),
 });
@@ -27,9 +33,14 @@ type StoredStateResponse = {
 
 const rootPath = "/auth";
 
-// Since this is a plugin
+// Since this is a plugin async should be used
 // eslint-disable-next-line @typescript-eslint/require-await
 const addPlugin = async (instance: FastifyInstance) => {
+  /**
+   * Authorize route, navigated too to get redirected to discord
+   * If redirect_to is set the user will be redirected to that after navigating to /callback
+   * This route also generates a state to be used in the oauth flow - which is used for security
+   */
   instance.get<{ Querystring: AuthorizeQuerystringType }>(
     `${rootPath}/authorize`,
     {
@@ -52,6 +63,13 @@ const addPlugin = async (instance: FastifyInstance) => {
       );
     }
   );
+  /**
+   * Callback route, navigated too after authorized with discord
+   * This route will get the user's access token and refresh token from discord
+   * Then it will get the user's data - and store that
+   * Then generate a token - a way of authentication between the user and the api
+   * Then redirect the user to the redirect_to path - if it was set
+   */
   instance.get<{ Querystring: CallbackQuerystringType }>(
     `${rootPath}/callback`,
     {
@@ -67,20 +85,27 @@ const addPlugin = async (instance: FastifyInstance) => {
       if (state === undefined) {
         return new Forbidden("Missing state");
       }
+      // State must be valid, present and the same - for security
       const cachedState = await instance.redisCache.getState(state);
       if (!cachedState) {
         return new Forbidden("Cannot find state, please try again");
       }
+      // Delete state so it cannot be used again - again for security
       await instance.redisCache.deleteState(state);
+
       const tokenResponse = await instance.discordOauthRequests.exchangeToken(
         code
       );
+      // If the required scopes are not set then the data required might not be accessible
       if (!DiscordOauthRequests.verifyScopes(tokenResponse.scope)) {
         return new Forbidden("Invalid scopes, please try again");
       }
       const user = await instance.discordOauthRequests.fetchUser({
         token: tokenResponse.access_token,
       });
+      // Create user in database - the token is stored here and not on the browser
+      // so the token does not get stolen, which could lead to actions under the bot's id being taken on
+      // behalf of the user that we do not want to happen
       await instance.prisma.user.upsert({
         where: { id: BigInt(user.id) },
         create: {
@@ -96,12 +121,14 @@ const addPlugin = async (instance: FastifyInstance) => {
         },
       });
 
+      // Session is to authenticate the client to the api
       const session = uuidv5(user.id, instance.envVars.UUID_NAMESPACE);
       await instance.redisCache.setSession(session, user.id);
       const date = new Date();
       date.setDate(date.getDate() + 7);
 
       const redirectPath = cachedState.redirectPath ?? "/";
+      // This cookie will be used to authenticate the client to the api
       return reply
         .setCookie("_HOST-session", session, {
           secure: true,

src/authRoutes.ts

@@ -1,11 +1,17 @@
-//const discordAPIBaseURL = "https://discord.com/api/v9";
-const discordAPIBaseURL = "https://discord-proxy.anothercat.workers.dev/api/v9";
+// Base url for making API requests to discord (other than through the discord.js client)
+const discordAPIBaseURL = "https://discord.com/api/v9";
+// Scopes to request and require in the oauth2 flow
+// identify to be able to identify the user
+// guilds to be able to get the guilds the user is in
+// and guilds.members.read to access the member object for the user in each guild
 const requiredScopes = ["identify", "guilds", "guilds.members.read"];
 
+// Integer color numbers for embed generation
 const embedPink = 12814273;
 const successGreen = 3066993;
 const failureRed = 15158332;
 
+// Url to invite the bot to a server - must be done by a user
 const inviteUrl =
   "https://discord.com/api/oauth2/authorize?client_id=735395698278924359&permissions=515933326400&scope=bot%20applications.commands";
 

src/constants.ts

@@ -1,4 +1,6 @@
+// Derived from
 // https://github.com/detritusjs/client/blob/b27cbaa5bfb48506b059be178da0e871b83ba95e/src/constants.ts#L917
+// and discord.com/developers/docs/topics/permissions
 const DiscordPermissions = Object.freeze({
   NONE: 0n,
   CREATE_INSTANT_INVITE: 1n << 0n,
@@ -42,6 +44,9 @@ const DiscordPermissions = Object.freeze({
   SEND_MESSAGES_IN_THREADS: 1n << 38n,
 });
 
+// Various functions to get the permission names / values, this is to assist with error and message generation about permissions
+// For example getting the name of a permission from the value
+
 const _permissionsByName: { [name: string]: bigint } = {};
 const _permissionsByValue: { [value: string]: string } = {};
 // Find the names and values of all the permissions from Permissions

src/consts.ts

@@ -1,3 +1,7 @@
+/**
+ * Custom client for making requests to Discord's OAuth2 API
+ */
+
 import axios, { AxiosError, AxiosResponse } from "axios";
 import {
   RESTGetAPICurrentUserGuildsResult,
@@ -17,6 +21,8 @@ import {
 } from "./errors";
 import { UserRequestData } from "./plugins/authentication";
 
+// Two different responses to differentiate between a cache and uncached response
+// This is because they need to be handled differently
 interface CachedResponse {
   cached: true;
   data: unknown;
@@ -30,6 +36,9 @@ class DiscordOauthRequests {
   constructor(instance: FastifyInstance) {
     this._instance = instance;
   }
+
+  // _makeRequest has two type overloads
+  // This one is for when the response can from the cache (so could be either uncached or cached)
   private async _makeRequest({
     path,
     method,
@@ -48,6 +57,7 @@ class DiscordOauthRequests {
     userId: Snowflake;
   }): Promise<UncachedResponse | CachedResponse>;
 
+  // This overload if for then the response cannot be from the cache (cacheExpiry is undefined)
   private async _makeRequest({
     path,
     method,
@@ -66,6 +76,7 @@ class DiscordOauthRequests {
     userId?: undefined;
   }): Promise<UncachedResponse>;
 
+  // Function to make all requests through - this is to allow for caching
   private async _makeRequest({
     path,
     method,
@@ -84,9 +95,9 @@ class DiscordOauthRequests {
     cacheExpiry?: number;
     userId?: Snowflake;
   }): Promise<UncachedResponse | CachedResponse> {
+    // If the cacheExpiry is defined and the request if from user, then the response can be cached
+    // Otherwise it cannot not
     if (cacheExpiry !== undefined && userId !== undefined) {
-      // TODO: Should cacheExpiry be checked / used
-      // Requests without a token are not cached
       const cachedResponse = (await this._instance.redisCache.getOauthCache(
         path,
         userId