From 7142c82c362000161e9c398440457cd45d015133 Mon Sep 17 00:00:00 2001 From: ethangardner Date: Fri, 3 Jan 2025 14:14:47 -0500 Subject: [PATCH] add jsdoc comments to the auth package --- packages/auth/src/context/base.ts | 6 ++++++ packages/auth/src/lucia.ts | 16 ++++++++++++---- packages/auth/src/provider.ts | 5 +++++ packages/auth/src/repository/create-session.ts | 7 ++++++- packages/auth/src/repository/create-user.ts | 6 ++++++ packages/auth/src/repository/get-user-id.ts | 6 ++++++ packages/auth/src/repository/index.ts | 11 +++++++++++ .../auth/src/services/get-provider-redirect.ts | 8 ++++++++ packages/auth/src/services/index.ts | 5 +++++ packages/auth/src/services/logout.ts | 9 +++++++-- .../src/services/process-provider-callback.ts | 14 ++++++++++++++ .../auth/src/services/process-session-cookie.ts | 10 ++++++++++ 12 files changed, 96 insertions(+), 7 deletions(-) diff --git a/packages/auth/src/context/base.ts b/packages/auth/src/context/base.ts index e4181e4f3..9a0c7f222 100644 --- a/packages/auth/src/context/base.ts +++ b/packages/auth/src/context/base.ts @@ -8,6 +8,12 @@ import { import { LoginGov } from '../provider.js'; import { type AuthRepository } from '../repository/index.js'; +/** + * The `BaseAuthContext` class implements the `AuthServiceContext` interface, + * providing an authentication context for user sessions and database interactions. + * It integrates with a repository for database operations, a third-party login provider, + * and various utilities for managing cookies and user sessions. + */ export class BaseAuthContext implements AuthServiceContext { private lucia?: Lucia; diff --git a/packages/auth/src/lucia.ts b/packages/auth/src/lucia.ts index 4761306d2..44a377462 100644 --- a/packages/auth/src/lucia.ts +++ b/packages/auth/src/lucia.ts @@ -5,20 +5,28 @@ import { Lucia } from 'lucia'; import { type Database } from '@atj/database'; +/** + * Factory function to create a SQLite Lucia adapter. + * + * @param {Sqlite3Database} db - The SQLite3 database instance used to initialize the adapter. + */ export const createSqliteLuciaAdapter = (db: Sqlite3Database) => { - const adapter = new BetterSqlite3Adapter(db, { + return new BetterSqlite3Adapter(db, { user: 'users', session: 'sessions', }); - return adapter; }; +/** + * Factory function to create a Postgres Lucia adapter. + * + * @param {Sqlite3Database} pgPool - The SQLite3 database instance used to initialize the adapter. + */ export const createPostgresLuciaAdapter = (pgPool: any) => { - const adapter = new NodePostgresAdapter(pgPool, { + return new NodePostgresAdapter(pgPool, { user: 'users', session: 'sessions', }); - return adapter; }; declare module 'lucia' { diff --git a/packages/auth/src/provider.ts b/packages/auth/src/provider.ts index 51ae383a4..e92825436 100644 --- a/packages/auth/src/provider.ts +++ b/packages/auth/src/provider.ts @@ -19,6 +19,11 @@ export type LoginGovOptions = { redirectURI?: string; }; +/** + * The LoginGov class implements the OAuth2ProviderWithPKCE interface + * and provides functionality to authenticate users using Login.gov's + * OAuth 2.0 with PKCE flow. + */ export class LoginGov implements OAuth2ProviderWithPKCE { private client: OAuth2Client; //private clientSecret: string; diff --git a/packages/auth/src/repository/create-session.ts b/packages/auth/src/repository/create-session.ts index 752c2a0af..5e39929aa 100644 --- a/packages/auth/src/repository/create-session.ts +++ b/packages/auth/src/repository/create-session.ts @@ -7,6 +7,12 @@ type Session = { userId: string; }; +/** + * Asynchronously creates a new session in the database. + * + * @param {DatabaseContext} ctx - The database context used to manage the connection and provide access to the database engine. + * @param {Session} session - The session data to be inserted, containing properties such as id, expiration time, session token, and user id. + */ export const createSession = async (ctx: DatabaseContext, session: Session) => { const db = await ctx.getKysely(); const result = await db.transaction().execute(async trx => { @@ -17,7 +23,6 @@ export const createSession = async (ctx: DatabaseContext, session: Session) => { expires_at: dateValue(ctx.engine, session.expiresAt), session_token: session.sessionToken, user_id: session.userId, - //...session.attributes, }) .execute(); }); diff --git a/packages/auth/src/repository/create-user.ts b/packages/auth/src/repository/create-user.ts index 8f618538e..8a9edded7 100644 --- a/packages/auth/src/repository/create-user.ts +++ b/packages/auth/src/repository/create-user.ts @@ -2,6 +2,12 @@ import { randomUUID } from 'crypto'; import { type DatabaseContext } from '@atj/database'; +/** + * Asynchronously creates a new user record in the database. + * + * @param {DatabaseContext} ctx - The database context used to interact with the database. + * @param {string} email - The email address of the user to be created. + */ export const createUser = async (ctx: DatabaseContext, email: string) => { const id = randomUUID(); diff --git a/packages/auth/src/repository/get-user-id.ts b/packages/auth/src/repository/get-user-id.ts index 4d4af6f3a..eab207304 100644 --- a/packages/auth/src/repository/get-user-id.ts +++ b/packages/auth/src/repository/get-user-id.ts @@ -1,5 +1,11 @@ import { type DatabaseContext } from '@atj/database'; +/** + * Retrieves the unique identifier (ID) of a user based on their email address. + * + * @param {DatabaseContext} ctx - The database context used to establish a connection and perform the query. + * @param {string} email - The email address of the user whose ID is to be retrieved. + */ export const getUserId = async (ctx: DatabaseContext, email: string) => { const db = await ctx.getKysely(); const user = await db.transaction().execute(trx => { diff --git a/packages/auth/src/repository/index.ts b/packages/auth/src/repository/index.ts index 84b6c3238..1a312478e 100644 --- a/packages/auth/src/repository/index.ts +++ b/packages/auth/src/repository/index.ts @@ -5,6 +5,17 @@ import { createSession } from './create-session.js'; import { createUser } from './create-user.js'; import { getUserId } from './get-user-id.js'; +/** + * Factory function to create an authentication repository. + * + * @param {DatabaseContext} ctx - The database context used for initializing the repository. + * @returns Returns an authentication service object with methods to handle user authentication and management. + * + * The returned service object provides the following methods: + * - `createSession` + * - `createUser` + * - `getUserId` + */ export const createAuthRepository = (ctx: DatabaseContext) => createService(ctx, { createSession, diff --git a/packages/auth/src/services/get-provider-redirect.ts b/packages/auth/src/services/get-provider-redirect.ts index 3988664dd..99cc0e958 100644 --- a/packages/auth/src/services/get-provider-redirect.ts +++ b/packages/auth/src/services/get-provider-redirect.ts @@ -1,6 +1,14 @@ import { generateCodeVerifier, generateState } from 'arctic'; import { type AuthServiceContext } from './index.js'; +/** + * Asynchronously generates a redirection URL for an OAuth authorization request and associated cookies. + * + * This function interacts with the provided authentication service context to create an authorization + * URL, including necessary state and verification parameters for security measures. + * + * @param {AuthServiceContext} ctx - The authentication service context used to interact with the provider. + */ export const getProviderRedirect = async (ctx: AuthServiceContext) => { const state = generateState(); const codeVerifier = generateCodeVerifier(); diff --git a/packages/auth/src/services/index.ts b/packages/auth/src/services/index.ts index d791ab9ea..7e60f93f6 100644 --- a/packages/auth/src/services/index.ts +++ b/packages/auth/src/services/index.ts @@ -22,6 +22,11 @@ export type AuthServiceContext = { isUserAuthorized: (email: string) => Promise; }; +/** + * Factory function to create an authentication service. + * + * @param {AuthServiceContext} ctx - The context required to initialize the authentication service. + */ export const createAuthService = (ctx: AuthServiceContext) => createService(ctx, { getProviderRedirect, diff --git a/packages/auth/src/services/logout.ts b/packages/auth/src/services/logout.ts index 00179c702..ddc816890 100644 --- a/packages/auth/src/services/logout.ts +++ b/packages/auth/src/services/logout.ts @@ -1,9 +1,14 @@ import { type Session } from 'lucia'; import { type AuthServiceContext } from './index.js'; +/** + * Logs out a user by invalidating their existing session and creating a blank session cookie. + * + * @param {AuthServiceContext} ctx - The authentication service context. + * @param {Session} session - The session object to be invalidated. + */ export const logOut = async (ctx: AuthServiceContext, session: Session) => { const lucia = await ctx.getLucia(); await lucia.invalidateSession(session.id); - const sessionCookie = lucia.createBlankSessionCookie(); - return sessionCookie; + return lucia.createBlankSessionCookie(); }; diff --git a/packages/auth/src/services/process-provider-callback.ts b/packages/auth/src/services/process-provider-callback.ts index 4d5ac9b2b..88a7e6f8b 100644 --- a/packages/auth/src/services/process-provider-callback.ts +++ b/packages/auth/src/services/process-provider-callback.ts @@ -18,6 +18,15 @@ type Params = { state?: string | null; }; +/** + * Processes the provider callback for an OAuth-based authentication flow. Ensures data integrity and security through checks like nonce matching, + * state validation, and proper error handling. + * + * @param {AuthServiceContext} ctx - The context object containing authentication services, database access, and related utilities. + * @param {Params} params - The parameters received from the provider as part of the callback request. + * @param {Params & { nonce: string | null }} storedParams - Locally stored parameters including the nonce for verification and validation. + * @param {function} [fetchUserData=fetchUserDataImpl] - A function to fetch user data from the external provider using the access token. + */ export const processProviderCallback = async ( ctx: AuthServiceContext, params: Params, @@ -91,6 +100,11 @@ export const processProviderCallback = async ( }); }; +/** + * Fetches user data from the login-provider endpoint using the provided access token with bearer token auth. + * + * @param {string} accessToken - The access token to authorize the request. + */ const fetchUserDataImpl = (accessToken: string) => fetch('https://idp.int.identitysandbox.gov/api/openid_connect/userinfo', { headers: { diff --git a/packages/auth/src/services/process-session-cookie.ts b/packages/auth/src/services/process-session-cookie.ts index 401a7122d..209cf2465 100644 --- a/packages/auth/src/services/process-session-cookie.ts +++ b/packages/auth/src/services/process-session-cookie.ts @@ -4,6 +4,16 @@ import { type VoidResult } from '@atj/common'; import { type AuthServiceContext } from './index.js'; +/** + * Processes the session cookie in the context of an authentication request. + * This function validates the session cookie from the incoming request and + * sets the appropriate user session in the given context. It checks the + * request's origin for security and handles session expiration or invalidation + * by creating blank session cookies when necessary. + * + * @param {AuthServiceContext} ctx - The authentication service context used to manage sessions and cookies. + * @param {Request} request - The incoming HTTP request object containing session and origin information. + */ export const processSessionCookie = async ( ctx: AuthServiceContext, request: Request