refactor: add docblocks

Author: thetutlage

src/debug.ts

@@ -8,4 +8,12 @@
  */
 
 import { debuglog } from 'node:util'
+
+/**
+ * Debug logger instance for the Shield package.
+ * Logs debug messages when NODE_DEBUG=adonisjs:shield is set.
+ *
+ * @example
+ * debug('csrf: ignoring request for "%s" method', ctx.request.method())
+ */
 export default debuglog('adonisjs:shield')

src/define_config.ts

@@ -10,7 +10,16 @@
 import type { ShieldConfig } from './types.ts'
 
 /**
- * Define shield configuration
+ * Define shield configuration with default values.
+ * Merges provided partial configuration with defaults where all guards are disabled by default.
+ *
+ * @param config - Partial shield configuration object
+ *
+ * @example
+ * const shieldConfig = defineConfig({
+ *   csrf: { enabled: true },
+ *   hsts: { enabled: true, maxAge: '1 year' }
+ * })
  */
 export function defineConfig(config: Partial<ShieldConfig>): ShieldConfig {
   return {

src/errors.ts

@@ -13,6 +13,13 @@ import type { I18n } from '@adonisjs/i18n'
 import { Exception } from '@adonisjs/core/exceptions'
 import { type HttpContext } from '@adonisjs/core/http'
 
+/**
+ * Exception class for invalid or expired CSRF tokens.
+ * Handles CSRF validation failures by flashing errors and redirecting back.
+ * 
+ * @example
+ * throw new E_BAD_CSRF_TOKEN()
+ */
 export const E_BAD_CSRF_TOKEN = class InvalidCSRFToken extends Exception {
   code = 'E_BAD_CSRF_TOKEN'
   status = 403
@@ -23,6 +30,9 @@ export const E_BAD_CSRF_TOKEN = class InvalidCSRFToken extends Exception {
    * Returns the message to be sent in the HTTP response.
    * Feel free to override this method and return a custom
    * response.
+   * 
+   * @param error - The error instance
+   * @param ctx - The HTTP context
    */
   getResponseMessage(error: this, ctx: HttpContext) {
     if ('i18n' in ctx) {
@@ -31,6 +41,13 @@ export const E_BAD_CSRF_TOKEN = class InvalidCSRFToken extends Exception {
     return error.message
   }
 
+  /**
+   * Handles the CSRF error by flashing session data and redirecting back.
+   * For non-Inertia requests, flashes all session data except sensitive fields.
+   * 
+   * @param error - The error instance
+   * @param ctx - The HTTP context
+   */
   async handle(error: this, ctx: HttpContext) {
     if (!ctx.request.header('X-Inertia')) {
       ctx.session.flashExcept(['_csrf', '_method', 'password', 'password_confirmation'])

src/guards/csp/keywords.ts

@@ -14,22 +14,33 @@ import type { ContentSecurityPolicyOptions } from '../../helmet-csp.cts'
 
 /**
  * A collection of CSP keywords that are resolved to actual values
- * during an HTTP request.
+ * during an HTTP request. Allows registration of dynamic CSP directive values.
+ *
+ * @example
+ * cspKeywords.register('@nonce', (req, res) => `'nonce-${res.nonce}'`)
  */
 class CSPKeywords {
+  /**
+   * Registry of keyword resolvers that transform keywords to CSP directive values
+   */
   #keywordsResolvers: Record<string, (_: IncomingMessage, response: ServerResponse) => string> = {}
 
   /**
-   * Register a custom CSP directive keyword and resolve
-   * it to a value during an HTTP request.
+   * Registers a custom CSP directive keyword and its resolver function.
+   * The resolver function transforms the keyword to an actual CSP value during requests.
+   *
+   * @param keyword - The keyword to register (e.g., '@nonce')
+   * @param resolver - Function that resolves the keyword to a CSP value
    */
   register(keyword: string, resolver: (_: IncomingMessage, response: ServerResponse) => string) {
     this.#keywordsResolvers[keyword] = resolver
     return this
   }
 
   /**
-   * Resolves keywords
+   * Resolves registered keywords in CSP directive values to their actual values.
+   *
+   * @param directiveValues - The directive values that may contain keywords
    */
   resolve(
     directiveValues: ValueOf<Exclude<ContentSecurityPolicyOptions['directives'], undefined>>
@@ -48,5 +59,11 @@ class CSPKeywords {
   }
 }
 
+/**
+ * Global instance of CSPKeywords for registering and resolving CSP directive keywords.
+ *
+ * @example
+ * cspKeywords.register('@nonce', (req, res) => `'nonce-${res.nonce}'`)
+ */
 const cspKeywords = new CSPKeywords()
 export { cspKeywords }

src/guards/csp/main.ts

@@ -27,7 +27,18 @@ cspKeywords.register('@nonce', function (_, response) {
 
 /**
  * Factory that returns a function to set the `Content-Security-Policy` header based upon
- * the user config
+ * the user configuration. Provides protection against XSS and code injection attacks.
+ *
+ * @param options - CSP configuration options
+ *
+ * @example
+ * const cspGuard = cspFactory({
+ *   enabled: true,
+ *   directives: {
+ *     defaultSrc: ["'self'"],
+ *     scriptSrc: ["'self'", '@nonce']
+ *   }
+ * })
  */
 export function cspFactory(options: CspOptions) {
   if (!options.enabled) {

src/guards/csrf.ts

@@ -61,6 +61,13 @@ export class CsrfGuard {
    */
   #edge?: Edge
 
+  /**
+   * Creates a new CsrfGuard instance.
+   *
+   * @param options - CSRF configuration options
+   * @param encryption - Encryption service instance
+   * @param edge - Optional Edge template engine instance
+   */
   constructor(options: CsrfOptions, encryption: Encryption, edge?: Edge) {
     this.#options = options
     this.#encryption = encryption
@@ -71,7 +78,10 @@ export class CsrfGuard {
   }
 
   /**
-   * Find if a request should be validated or not
+   * Determines if a request should be validated for CSRF tokens.
+   * Checks against allowed methods and routes to ignore.
+   *
+   * @param ctx - HTTP context object
    */
   #shouldValidateRequest(ctx: HttpContext) {
     /**
@@ -106,12 +116,12 @@ export class CsrfGuard {
   }
 
   /**
-   * Read csrf token from one of the following sources.
+   * Reads CSRF token from one of the following sources:
+   * - `_csrf` form input field
+   * - `x-csrf-token` request header
+   * - `x-xsrf-token` header (when XSRF cookie is enabled)
    *
-   * - `_csrf` input
-   * - `x-csrf-token` header
-   * - Or `x-xsrf-token` header. The header value must be set by
-   *   reading the `XSRF-TOKEN` cookie.
+   * @param ctx - HTTP context object containing the request
    */
   #getCsrfTokenFromRequest({ request }: HttpContext): string | null {
     if (request.input('_csrf')) {
@@ -142,7 +152,10 @@ export class CsrfGuard {
   }
 
   /**
-   * Share csrf helper methods with the view engine.
+   * Shares CSRF helper methods with the view engine.
+   * Makes csrfToken, csrfMeta(), and csrfField() available in templates.
+   *
+   * @param ctx - HTTP context object
    */
   #shareCsrfViewLocals(ctx: HttpContext): void {
     if (!ctx.view || !this.#edge) {
@@ -165,16 +178,19 @@ export class CsrfGuard {
   }
 
   /**
-   * Generate a new csrf token using the csrf secret extracted from session.
+   * Generates a new CSRF token using the CSRF secret extracted from session.
+   *
+   * @param csrfSecret - The CSRF secret from the user's session
    */
   #generateCsrfToken(csrfSecret: string): string {
     return this.#tokens.create(csrfSecret)
   }
 
   /**
-   * Return the existing CSRF secret from the session or create a
-   * new one. Newly created secret is persisted to session at
-   * the same time
+   * Returns the existing CSRF secret from the session or creates a new one.
+   * Newly created secrets are persisted to the session automatically.
+   *
+   * @param ctx - HTTP context object
    */
   async #getCsrfSecret(ctx: HttpContext): Promise<string> {
     let csrfSecret = ctx.session.get(this.#secretSessionKey)
@@ -189,10 +205,11 @@ export class CsrfGuard {
   }
 
   /**
-   * Handle csrf verification. First, get the secret,
-   * next, check if the request method should be
-   * verified. Next, attach the newly generated
-   * csrf token to the request object.
+   * Handles CSRF verification for the current request.
+   * Gets or creates a CSRF secret, generates a token, optionally sets XSRF cookie,
+   * shares helpers with views, and validates the request if required.
+   *
+   * @param ctx - HTTP context object
    */
   async handle(ctx: HttpContext): Promise<void> {
     const csrfSecret = await this.#getCsrfSecret(ctx)
@@ -230,8 +247,18 @@ export class CsrfGuard {
 }
 
 /**
- * A factory function that returns a new function to enforce CSRF
- * protection
+ * A factory function that returns a new function to enforce CSRF protection.
+ * Creates a CsrfGuard instance and returns its handle method.
+ *
+ * @param options - CSRF configuration options
+ * @param encryption - Encryption service instance
+ * @param edge - Optional Edge template engine instance
+ *
+ * @example
+ * const csrfGuard = csrfFactory({
+ *   enabled: true,
+ *   methods: ['POST', 'PUT', 'DELETE']
+ * }, encryption, edge)
  */
 export function csrfFactory(options: CsrfOptions, encryption: Encryption, edge?: Edge) {
   if (!options.enabled) {

src/guards/frame_guard.ts

@@ -16,7 +16,15 @@ const ALLOWED_ACTIONS = ['DENY', 'ALLOW-FROM', 'SAMEORIGIN']
 
 /**
  * Factory function that returns a function to set `X-Frame-Options` header
- * based upon given user options.
+ * based upon given user options. Prevents clickjacking attacks.
+ *
+ * @param options - Frame guard configuration options
+ *
+ * @example
+ * const frameGuard = frameGuardFactory({
+ *   enabled: true,
+ *   action: 'SAMEORIGIN'
+ * })
  */
 export function frameGuardFactory(options: XFrameOptions) {
   if (!options.enabled) {

src/guards/hsts.ts

@@ -16,7 +16,10 @@ import type { HstsOptions } from '../types.ts'
 const DEFAULT_MAX_AGE = 180 * 24 * 60 * 60
 
 /**
- * Normalizes the max age to seconds
+ * Normalizes the max age to seconds.
+ * Converts string-based time expressions to seconds or uses the provided number.
+ *
+ * @param maxAge - The max age value as string (e.g., '1 year') or number (seconds)
  */
 function normalizeMaxAge(maxAge?: string | number): number {
   if (maxAge === null || maxAge === undefined) {
@@ -32,8 +35,17 @@ function normalizeMaxAge(maxAge?: string | number): number {
 }
 
 /**
- * Factory function that returns a new function to Add `Strict-Transport-Security`
- * header based upon given user options.
+ * Factory function that returns a new function to add `Strict-Transport-Security`
+ * header based upon given user options. Enables HTTPS enforcement for enhanced security.
+ *
+ * @param options - HSTS configuration options
+ *
+ * @example
+ * const hstsGuard = hstsFactory({
+ *   enabled: true,
+ *   maxAge: '1 year',
+ *   includeSubDomains: true
+ * })
  */
 export function hstsFactory(options: HstsOptions) {
   if (!options.enabled) {

src/guards/no_sniff.ts

@@ -12,8 +12,13 @@ import type { ContentTypeSniffingOptions } from '../types.ts'
 import { noop } from '../noop.ts'
 
 /**
- * Factory function that returns a function to Add `X-Content-Type-Options`
- * header based upon given user options.
+ * Factory function that returns a function to add `X-Content-Type-Options`
+ * header based upon given user options. Prevents MIME type sniffing attacks.
+ *
+ * @param options - Content type sniffing configuration options
+ *
+ * @example
+ * const noSniffGuard = noSniffFactory({ enabled: true })
  */
 export function noSniffFactory(options: ContentTypeSniffingOptions) {
   if (!options.enabled) {

src/noop.ts

@@ -8,4 +8,15 @@
  */
 
 import type { HttpContext } from '@adonisjs/core/http'
+
+/**
+ * A no-operation function that does nothing with the provided HTTP context.
+ * Used as a placeholder when a guard is disabled.
+ *
+ * @param _ - The HTTP context (unused)
+ *
+ * @example
+ * const guard = options.enabled ? actualGuard : noop
+ * guard(ctx)
+ */
 export function noop(_: HttpContext) {}