refactor: add docblocks

Author: thetutlage

src/encryption.ts

@@ -23,6 +23,9 @@ import { MessageVerifier } from './message_verifier.ts'
  * security (read more https://en.wikipedia.org/wiki/Semantic_security).
  */
 export class Encryption {
+  /**
+   * Configuration options for the encryption instance
+   */
   #options: Required<EncryptionOptions>
 
   /**
@@ -50,11 +53,18 @@ export class Encryption {
 
   /**
    * The algorithm in use
+   *
+   * @returns The encryption algorithm being used
    */
   get algorithm(): 'aes-256-cbc' {
     return this.#options.algorithm
   }
 
+  /**
+   * Creates a new Encryption instance with the provided options
+   *
+   * @param options - Configuration options for encryption
+   */
   constructor(options: EncryptionOptions) {
     const secretValue =
       options.secret && typeof options.secret === 'object' && 'release' in options.secret
@@ -69,8 +79,10 @@ export class Encryption {
 
   /**
    * Validates the app secret
+   *
+   * @param secret - The secret to validate
    */
-  #validateSecret(secret?: string) {
+  #validateSecret(secret?: string): void {
     if (typeof secret !== 'string') {
       throw new errors.E_MISSING_APP_KEY()
     }
@@ -93,8 +105,13 @@ export class Encryption {
    *
    * You can optionally define a purpose for which the value was encrypted and
    * mentioning a different purpose/no purpose during decrypt will fail.
+   *
+   * @param payload - The data to be encrypted
+   * @param expiresIn - Optional expiration time
+   * @param purpose - Optional purpose for which the value is encrypted
+   * @returns The encrypted payload as a string
    */
-  encrypt(payload: any, expiresIn?: string | number, purpose?: string) {
+  encrypt(payload: any, expiresIn?: string | number, purpose?: string): string {
     /**
      * Using a random string as the iv for generating unpredictable values
      */
@@ -132,6 +149,10 @@ export class Encryption {
 
   /**
    * Decrypt value and verify it against a purpose
+   *
+   * @param value - The encrypted value to decrypt
+   * @param purpose - Optional purpose that the value was encrypted for
+   * @returns The decrypted data if valid, null if decryption fails
    */
   decrypt<T extends any>(value: unknown, purpose?: string): T | null {
     if (typeof value !== 'string') {
@@ -191,8 +212,11 @@ export class Encryption {
 
   /**
    * Create a children instance with different secret key
+   *
+   * @param options - Optional configuration options to override
+   * @returns A new Encryption instance with the merged options
    */
-  child(options?: EncryptionOptions) {
+  child(options?: EncryptionOptions): Encryption {
     return new Encryption({ ...this.#options, ...options })
   }
 }

src/errors.ts

@@ -9,11 +9,20 @@
 
 import { createError } from '@poppinss/utils/exception'
 
+/**
+ * Error thrown when the application key is too short to be secure.
+ * The application key must be at least 16 characters long to ensure
+ * adequate security for encryption operations.
+ */
 export const E_INSECURE_APP_KEY = createError(
   'The value of "app.appKey" should be atleast 16 characters long',
   'E_INSECURE_APP_KEY'
 )
 
+/**
+ * Error thrown when the application key is missing from the configuration.
+ * The application key is required for all encryption and decryption operations.
+ */
 export const E_MISSING_APP_KEY = createError(
   'Missing "app.appKey". The key is required to encrypt values',
   'E_MISSING_APP_KEY'

src/hmac.ts

@@ -16,23 +16,38 @@ import base64 from '@poppinss/utils/base64'
  * integrity.
  */
 export class Hmac {
+  /**
+   * The cryptographic key used for HMAC generation
+   */
   #key: Buffer
 
+  /**
+   * Creates a new HMAC instance with the provided cryptographic key
+   *
+   * @param key - The buffer containing the cryptographic key
+   */
   constructor(key: Buffer) {
     this.#key = key
   }
 
   /**
    * Generate the hmac
+   *
+   * @param value - The string value to generate HMAC for
+   * @returns The base64 URL encoded HMAC hash
    */
-  generate(value: string) {
+  generate(value: string): string {
     return base64.urlEncode(createHmac('sha256', this.#key).update(value).digest('hex'))
   }
 
   /**
    * Compare raw value against an existing hmac
+   *
+   * @param value - The original string value
+   * @param existingHmac - The existing HMAC to compare against
+   * @returns True if the HMACs match, false otherwise
    */
-  compare(value: string, existingHmac: string) {
+  compare(value: string, existingHmac: string): boolean {
     return safeEqual(this.generate(value), existingHmac)
   }
 }

src/message_verifier.ts

@@ -34,6 +34,11 @@ export class MessageVerifier {
    */
   #separator = '.'
 
+  /**
+   * Creates a new MessageVerifier instance with the provided secret
+   *
+   * @param secret - The secret key used for signing operations
+   */
   constructor(secret: string) {
     this.#cryptoKey = createHash('sha256').update(secret).digest()
   }
@@ -51,8 +56,13 @@ export class MessageVerifier {
    *
    * You can optionally define a purpose for which the value was signed and
    * mentioning a different purpose/no purpose during unsign will fail.
+   *
+   * @param payload - The data to be signed
+   * @param expiresIn - Optional expiration time
+   * @param purpose - Optional purpose for which the value is signed
+   * @returns The signed payload as a string
    */
-  sign(payload: any, expiresIn?: string | number, purpose?: string) {
+  sign(payload: any, expiresIn?: string | number, purpose?: string): string {
     if (payload === null || payload === undefined) {
       throw new RuntimeException(`Cannot sign "${payload}" value`)
     }
@@ -63,6 +73,10 @@ export class MessageVerifier {
 
   /**
    * Unsign a previously signed value with an optional purpose
+   *
+   * @param payload - The signed payload string to verify
+   * @param purpose - Optional purpose that the value was signed for
+   * @returns The original data if valid, null if invalid or verification fails
    */
   unsign<T extends any>(payload: string, purpose?: string): T | null {
     if (typeof payload !== 'string') {