{"id":15713769,"url":"https://github.com/axentro/crystal-two-factor-auth","last_synced_at":"2025-05-12T13:28:42.685Z","repository":{"id":140836182,"uuid":"134900898","full_name":"Axentro/crystal-two-factor-auth","owner":"Axentro","description":"Two Factor Authentication Crystal code implementing the Time-based One-time Password Algorithm","archived":false,"fork":false,"pushed_at":"2024-01-04T13:12:35.000Z","size":12,"stargazers_count":24,"open_issues_count":1,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-31T22:34:52.907Z","etag":null,"topics":["2fa","crystal-language","totp","two-factor-authentication"],"latest_commit_sha":null,"homepage":null,"language":"Crystal","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/Axentro.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-05-25T20:17:04.000Z","updated_at":"2025-01-29T09:34:15.000Z","dependencies_parsed_at":null,"dependency_job_id":"cab03ac6-dda5-41fd-a45e-832920055cc1","html_url":"https://github.com/Axentro/crystal-two-factor-auth","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Axentro%2Fcrystal-two-factor-auth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Axentro%2Fcrystal-two-factor-auth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Axentro%2Fcrystal-two-factor-auth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Axentro%2Fcrystal-two-factor-auth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Axentro","download_url":"https://codeload.github.com/Axentro/crystal-two-factor-auth/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253747388,"owners_count":21957750,"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","crystal-language","totp","two-factor-authentication"],"created_at":"2024-10-03T21:33:21.892Z","updated_at":"2025-05-12T13:28:42.663Z","avatar_url":"https://github.com/Axentro.png","language":"Crystal","funding_links":[],"categories":[],"sub_categories":[],"readme":"# crystal-two-factor-auth\n\n[![Build Status](https://travis-ci.org/SushiChain/crystal-two-factor-auth.svg?branch=master)](https://travis-ci.org/SushiChain/crystal-two-factor-auth)\n\nTwo (2) Factor Authentication (2FA) Crystal code which uses the Time-based One-time Password (TOTP) algorithm. You can use this code with the Google Authenticator mobile app or the Authy mobile or browser app.\n\n* See the [wikipedia page about TOTP](https://en.wikipedia.org/wiki/Time-based_One-time_Password_algorithm)\n\n## Installation\n\nAdd this to your application's `shard.yml`:\n\n```yaml\ndependencies:\n  crystal-two-factor-auth:\n    github: SushiChain/crystal-two-factor-auth\n```\n\n## Usage\n\n```crystal\nrequire \"crystal-two-factor-auth\"\n\n# TOTP.generate_base32_secret\nbase32_secret = \"NY4A5CPJZ46LXZCP\"\n\n# this is the name of the key which can be displayed by the authenticator program\nkey_id = \"kings@sushichain.io\"\n\n# generate the QR code\n# we can display this image to the user to let them load it into their auth program\nputs \"Image url: #{TOTP.qr_code_url(key_id, base32_secret)}\"\n\n# we can use the auth number here and compare it against user input\n# auth_number = TOTP.generate_number_string(base32_secret)\n# is_valid = TOTP.validate_number_string(base32_secret, auth_number)\n\n# this loop shows how the number changes over time\nwhile true\n  diff = TOTP::DEFAULT_TIME_STEP_SECONDS - ((Time.now.epoch_ms / 1000) % TOTP::DEFAULT_TIME_STEP_SECONDS)\n  code = TOTP.generate_number_string(base32_secret)\n  puts \"Secret code = #{code}, change in #{diff} seconds\"\n  sleep 1\nend\n```\n\nSee the example in `spec/two_factor_auth_example.cr`\n\n### To get this to work for you:\n\n1. Use `generate_base32_secret()` to generate a secret key in base32 format for the user. For example: `\"NY4A5CPJZ46LXZCP\"`\n2. Store the secret key in the database associated with the user account\n3. Display the QR image URK returned by `qr_code_url(...)` to the user. Here's a sample which uses GoogleAPI's:\n![Sample QR Image](https://chart.googleapis.com/chart?chs=200x200\u0026cht=qr\u0026chl=200x200\u0026chld=M|0\u0026cht=qr\u0026chl=otpauth://totp/kings@sushichain.io%3Fsecret%3DNY4A5CPJZ46LXZCP)\n4. User uses the image to load the secret key into their authenticator application (google auth / authy)\n\n### Whenever the user logs in:\n\n1. The user enters the number from the authenticator application into the login form\n2. Read the secret associated with the user account from the database\n3. The server compares the user input with the output from `generate_current_number_string(...)`\n4. If they are equal then the user is allowed to log in\n\n\n## Contributing\n\n1. Fork it ( https://github.com/SushiChain/crystal-two-factor-auth/fork )\n2. Create your feature branch (git checkout -b my-new-feature)\n3. Commit your changes (git commit -am 'Add some feature')\n4. Push to the branch (git push origin my-new-feature)\n5. Create a new Pull Request\n\n## Contributors\n\n- [kingsleyh](https://github.com/kingsleyh) Kingsley Hendrickse - creator, maintainer\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faxentro%2Fcrystal-two-factor-auth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faxentro%2Fcrystal-two-factor-auth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faxentro%2Fcrystal-two-factor-auth/lists"}