feat: Add generateRecoveryCodes method

Author: elpete

README.md

@@ -70,6 +70,18 @@ Generates a QR Code to use with authenticator apps containing the authenticator
 | width            | numeric | false    | 128     | The width of the QR code.                                                         |
 | height           | numeric | false    | 128     | The height of the QR code.                                                        |
 
+#### `generateRecoveryCodes`
+
+Generates an array of recovery codes.
+
+Each code composed of numbers and lower case characters from latin alphabet (36 possible characters).
+The code is split in groups separated with dash for better readability.
+For example: `4ckn-xspn-et8t-xgr0`
+
+| Name   | Type    | Required | Default | Description                      |
+| ------ | ------- | -------- | ------- | -------------------------------- |
+| amount | numeric | true     |         | The amount of codes to generate. |
+
 #### `generateCode`
 
 Generates a Time-based One-time Password (TOTP) for a given secret.

models/TOTP.cfc

@@ -108,6 +108,59 @@ component singleton accessors="true" {
         );
     }
 
+    /**
+     * Generates an array of recovery codes.
+     *
+     * @amount   The amount of codes to generate.
+     *
+     * @returns  An array of recovery codes.
+     */
+    public array function generateRecoveryCodes( required numeric amount ) {
+        if ( arguments.amount <= 0 ) {
+            throw(
+                type = "totp.InvalidRecoveryCodeAmount",
+                message = "You must generate a positive amount of recovery codes."
+            );
+        }
+
+        var codes = [];
+        for ( var i = 1; i <= arguments.amount; i++ ) {
+            codes.append( generateRecoveryCode() );
+        }
+        return codes;
+    }
+
+    /**
+     * Generates a code composed of numbers and lower case characters from latin alphabet (36 possible characters).
+     * The code is split in groups separated with dash for better readability.
+     * For example: `4ckn-xspn-et8t-xgr0`
+     *
+     * Recovery codes must reach a minimum entropy to be secured
+     * `code entropy = log( {characters-count} ^ {code-length} ) / log(2)`
+     * The settings used below allows the code to reach an entropy of 82 bits :
+     * log(36^16) / log(2) == 82.7...
+     *
+     * @returns  A recovery code string.
+     */
+    private string function generateRecoveryCode() {
+        var CODE_LENGTH = 16;
+        var GROUPS_NUMBER = 4;
+        var CHARACTERS = listToArray( "abcdefghijklmnopqrstuvwxyz0123456789", "" );
+        var CHARACTERS_LENGTH = CHARACTERS.len();
+
+        var code = "";
+        for ( var i = 1; i <= CODE_LENGTH; i++ ) {
+            // Append random character from authorized ones
+            code &= CHARACTERS[ variables.secureRandom.nextInt( CHARACTERS_LENGTH ) + 1 ];
+            // Split code into groups for increased readability
+            if ( i % GROUPS_NUMBER == 0 && i != CODE_LENGTH ) {
+                code &= "-";
+            }
+        }
+
+        return code;
+    }
+
     /**
      * Generates a TOTP for a given secret.
      *

tests/specs/unit/TOTPSpec.cfc

@@ -161,6 +161,35 @@ component extends="testbox.system.BaseSpec" {
                 } );
             } );
 
+            describe( "generateRecoveryCodes", function() {
+                it( "generates human-readable recovery codes", function() {
+                    var codes = variables.totp.generateRecoveryCodes( 4 );
+                    expect( codes ).toBeArray();
+                    expect( codes ).toHaveLength( 4 );
+
+                    var uniqueCodes = {};
+                    for ( var code in codes ) {
+                        expect( code ).toMatchWithCase(
+                            "[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}",
+                            "Recovery code does not match the expected format."
+                        );
+                        uniqueCodes[ code ] = "";
+                    }
+
+                    expect( uniqueCodes ).toHaveLength( 4, "All codes should be unique" );
+                } );
+
+                it( "throws an excpetion if the amount is not positive", function() {
+                    expect( function() {
+                        var codes = variables.totp.generateRecoveryCodes( 0 );
+                    } ).toThrow( type = "totp.InvalidRecoveryCodeAmount" );
+
+                    expect( function() {
+                        var codes = variables.totp.generateRecoveryCodes( -2 );
+                    } ).toThrow( type = "totp.InvalidRecoveryCodeAmount" );
+                } );
+            } );
+
             it( "can use a generated secret to generate and verify a code", function() {
                 var secret = variables.totp.generateSecret();
                 var code = variables.totp.generateCode( secret );