{"id":18578335,"url":"https://github.com/astrotomic/laravel-auth-recovery-codes","last_synced_at":"2025-04-10T10:31:06.916Z","repository":{"id":47162721,"uuid":"284008331","full_name":"Astrotomic/laravel-auth-recovery-codes","owner":"Astrotomic","description":null,"archived":false,"fork":false,"pushed_at":"2021-09-10T11:42:08.000Z","size":52,"stargazers_count":8,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-10-29T21:06:01.329Z","etag":null,"topics":["2fa","authentication","hacktoberfest","laravel","mfa","multi-factor-authentication","recovery-codes","tfa","treeware","two-factor-authentication"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Astrotomic.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-07-31T10:27:24.000Z","updated_at":"2022-11-17T13:38:40.000Z","dependencies_parsed_at":"2022-09-15T16:41:19.326Z","dependency_job_id":null,"html_url":"https://github.com/Astrotomic/laravel-auth-recovery-codes","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Astrotomic%2Flaravel-auth-recovery-codes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Astrotomic%2Flaravel-auth-recovery-codes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Astrotomic%2Flaravel-auth-recovery-codes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Astrotomic%2Flaravel-auth-recovery-codes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Astrotomic","download_url":"https://codeload.github.com/Astrotomic/laravel-auth-recovery-codes/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248199136,"owners_count":21063641,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["2fa","authentication","hacktoberfest","laravel","mfa","multi-factor-authentication","recovery-codes","tfa","treeware","two-factor-authentication"],"created_at":"2024-11-06T23:34:43.802Z","updated_at":"2025-04-10T10:31:06.523Z","avatar_url":"https://github.com/Astrotomic.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Laravel Auth Recovery-Codes\n\n[![Latest Version](http://img.shields.io/packagist/v/astrotomic/laravel-auth-recovery-codes.svg?label=Release\u0026style=for-the-badge)](https://packagist.org/packages/astrotomic/laravel-auth-recovery-codes)\n[![MIT License](https://img.shields.io/github/license/Astrotomic/laravel-auth-recovery-codes.svg?label=License\u0026color=blue\u0026style=for-the-badge)](https://github.com/Astrotomic/laravel-auth-recovery-codes/blob/master/LICENSE)\n[![Offset Earth](https://img.shields.io/badge/Treeware-%F0%9F%8C%B3-green?style=for-the-badge)](https://plant.treeware.earth/Astrotomic/laravel-auth-recovery-codes)\n[![Larabelles](https://img.shields.io/badge/Larabelles-%F0%9F%A6%84-lightpink?style=for-the-badge)](https://www.larabelles.com/)\n\n[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/Astrotomic/laravel-auth-recovery-codes/run-tests?style=flat-square\u0026logoColor=white\u0026logo=github\u0026label=Tests)](https://github.com/Astrotomic/laravel-auth-recovery-codes/actions?query=workflow%3Arun-tests)\n[![StyleCI](https://styleci.io/repos/284008331/shield)](https://styleci.io/repos/284008331)\n[![Total Downloads](https://img.shields.io/packagist/dt/astrotomic/laravel-auth-recovery-codes.svg?label=Downloads\u0026style=flat-square)](https://packagist.org/packages/astrotomic/laravel-auth-recovery-codes)\n\nThis package provides Laravel bindings and a Eloquent/Model trait for [pragmarx/recovery](https://github.com/antonioribeiro/recovery) package.\nIt allows you to easily handle recovery codes, needed for 2FA setups and only care about the app logic.\n\n## Installation\n\nYou can install the package via composer:\n\n```bash\ncomposer require astrotomic/laravel-auth-recovery-codes\n```\n\nAnd publish the config via artisan:\n\n```bash\nphp artisan vendor:publish --provider=\"Astrotomic\\AuthRecoveryCodes\\AuthRecoveryCodesServiceProvider\" --tag=config\n```\n\n## Usage\n\n### Model\n\nYou will have to add the `Recoverable` trait to your model you want to have recovery codes and should add a `json` or `array` cast to the attribute holding the recovery codes.\n\n```php\nuse Illuminate\\Database\\Eloquent\\Model;\nuse Astrotomic\\AuthRecoveryCodes\\Recoverable;\n\nclass User extends Model\n{\n    use Recoverable;\n\n    protected $casts = [\n        'recovery_codes' =\u003e 'array',\n    ];\n}\n```\n\nBy default the trait uses a `recovery_codes` attribute/column - you can change this by setting `$recoveryCodesName` property:\n\n```php\nclass User extends Model\n{\n    use Recoverable;\n\n    protected string $recoveryCodesName = 'mfa_recovery_codes';\n\n    protected $casts = [\n        'mfa_recovery_codes' =\u003e 'array',\n    ];\n}\n```\n\nTo set the new recovery codes to your model you should use the `setRecoveryCodes()` method because this method automatically hashes the recovery codes, if not already hashed.\nThis step is important for security because with this step only the user has access to the recovery codes and no one else.\nThe following snippet is an example of a possible controller action\n\n-   generating the codes\n-   setting and saving the codes on the user model\n-   responding with the codes to the user (the one and only time anyone can get/read the plaintext recovery codes)\n\n```php\n$codes = User::generateRecoveryCodes();\n\n$user-\u003esetRecoveryCodes($codes)-\u003esave();\n\nreturn response()-\u003ejson($codes);\n```\n\nIf you want to use the default model attribute without the need to use `setRecoveryCodes()` method you should add your own accessor and mutator, keep in mind to call the `Recoverable::hashRecoveryCodes()` method on set and that you have to do the JSON casting by your own.\n\n### Migration\n\nAfter setting up your model you will have to add the new column to your database table, there aren't much requirements - the `json` column type would only help to prevent invalid content, but the recovery codes JSON isn't really queryable (only an array of hashes), but the column should be `nullable` if you don't setup recovery codes on user create/register.\n\n```php\n\u003c?php\n\nuse Illuminate\\Database\\Migrations\\Migration;\nuse Illuminate\\Database\\Schema\\Blueprint;\nuse Illuminate\\Support\\Facades\\Schema;\n\nclass AddRecoveryCodesToUsersTable extends Migration\n{\n    public function up(): void\n    {\n        Schema::table('users', static function (Blueprint $table): void {\n            $table-\u003ejson('recovery_codes')-\u003enullable();\n        });\n    }\n\n    public function down(): void\n    {\n        Schema::table('users', static function (Blueprint $table): void {\n            $table-\u003edropColumn('recovery_codes');\n        });\n    }\n}\n```\n\n### Recovery\n\nNow that you have setup your app to generate and store recovery codes you should add the logic to recover an account.\nThe `Recoverable` trait comes with two methods to help you with this task.\n\n-   `isValidRecoveryCode()` return a `bool` and tells you if any of the saved recovery codes matches the input\n-   `useRecoveryCode()` removes the matching hash from the array and sets the array of remaining recovery codes\n\n```php\nuse Astrotomic\\AuthRecoveryCodes\\Recoverable;\nuse Illuminate\\Database\\Eloquent\\Model;\nuse Illuminate\\Http\\Request;\nuse Illuminate\\Support\\Facades\\Hash;\nuse Symfony\\Component\\HttpFoundation\\Response;\n\nclass RecoverController\n{\n    public function __invoke(Request $request)\n    {\n        /** @var Model|Recoverable $user */\n        $user = User::whereEmail($request-\u003eemail)-\u003efirstOrFail();\n\n        abort_unless(Hash::check($request-\u003epassword, $user-\u003epassword), Response::HTTP_NOT_FOUND);\n\n        abort_unless($user-\u003eisValidRecoveryCode($request-\u003erecovery_code), Response::HTTP_NOT_FOUND);\n\n        // do something to allow the user to recover the account\n        // - log them in and redirect to account/security settings\n        // - disable 2FA\n        // - send an email with a signed link to do something\n\n        $user-\u003euseRecoveryCode($request-\u003erecovery_code)-\u003esave();\n\n        // you should check if user has remaining recovery codes\n        // if not you should re-generate some and tell the user\n        // for sure you can trigger this before all codes are used\n        // or remind the user on regular login to generate new ones\n        // if he's running out of remaining ones\n        if(empty($user-\u003egetRecoveryCodes())) {\n            $codes = User::generateRecoveryCodes();\n\n            $user-\u003esetRecoveryCodes($codes)-\u003esave();\n\n            return response()-\u003ejson($codes);\n        }\n    }\n}\n```\n\n## Testing\n\n```bash\ncomposer test\n```\n\n## Changelog\n\nPlease see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.\n\n## Contributing\n\nPlease see [CONTRIBUTING](https://github.com/Astrotomic/.github/blob/master/CONTRIBUTING.md) for details. You could also be interested in [CODE OF CONDUCT](https://github.com/Astrotomic/.github/blob/master/CODE_OF_CONDUCT.md).\n\n### Security\n\nIf you discover any security related issues, please check [SECURITY](https://github.com/Astrotomic/.github/blob/master/SECURITY.md) for steps to report it.\n\n## Credits\n\n-   [Tom Witkowski](https://github.com/Gummibeer)\n-   [All Contributors](../../contributors)\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n\n## Treeware\n\nYou're free to use this package, but if it makes it to your production environment I would highly appreciate you buying the world a tree.\n\nIt’s now common knowledge that one of the best tools to tackle the climate crisis and keep our temperatures from rising above 1.5C is to [plant trees](https://www.bbc.co.uk/news/science-environment-48870920). If you contribute to my forest you’ll be creating employment for local families and restoring wildlife habitats.\n\nYou can buy trees at [offset.earth/treeware](https://plant.treeware.earth/Astrotomic/laravel-auth-recovery-codes)\n\nRead more about Treeware at [treeware.earth](https://treeware.earth)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fastrotomic%2Flaravel-auth-recovery-codes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fastrotomic%2Flaravel-auth-recovery-codes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fastrotomic%2Flaravel-auth-recovery-codes/lists"}