{"id":27962608,"url":"https://github.com/coretheory/pwned_coretheory","last_synced_at":"2025-06-18T17:39:11.255Z","repository":{"id":41446412,"uuid":"332541772","full_name":"coretheory/pwned_coretheory","owner":"coretheory","description":"A simple Elixir library to check passwords and emails with the HaveIBeenPwned? database.","archived":false,"fork":false,"pushed_at":"2022-10-17T06:35:30.000Z","size":165,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-07T19:56:41.431Z","etag":null,"topics":["elixir","haveibeenpwned"],"latest_commit_sha":null,"homepage":"https://github.com/coretheory/pwned_coretheory","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/coretheory.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null}},"created_at":"2021-01-24T19:53:03.000Z","updated_at":"2024-04-17T18:22:47.000Z","dependencies_parsed_at":"2022-09-07T16:50:28.325Z","dependency_job_id":null,"html_url":"https://github.com/coretheory/pwned_coretheory","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/coretheory/pwned_coretheory","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coretheory%2Fpwned_coretheory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coretheory%2Fpwned_coretheory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coretheory%2Fpwned_coretheory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coretheory%2Fpwned_coretheory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/coretheory","download_url":"https://codeload.github.com/coretheory/pwned_coretheory/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coretheory%2Fpwned_coretheory/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260600479,"owners_count":23034718,"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":["elixir","haveibeenpwned"],"created_at":"2025-05-07T19:56:39.518Z","updated_at":"2025-06-18T17:39:06.242Z","avatar_url":"https://github.com/coretheory.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Core Theory logo](assets/static/images/CT_Logo_Text.png)\n\n# Pwned by Core Theory\n\n![Master](https://github.com/coretheory/pwned_coretheory/workflows/Master/badge.svg?branch=master)\n![Staging](https://github.com/coretheory/pwned_coretheory/workflows/Staging/badge.svg)\n[![Hex.pm](https://img.shields.io/hexpm/v/pwned_coretheory.svg)](https://hex.pm/packages/pwned_coretheory)\n[![Docs](https://img.shields.io/badge/hex-docs-green.svg)](https://hexdocs.pm/pwned_coretheory/readme.html)\n[![Downloads](https://img.shields.io/hexpm/dt/pwned_coretheory.svg)](https://hex.pm/packages/pwned_coretheory)\n\n\nA simple application to check if an email or password has been pwned using the HaveIbeenPwned? API v3.\n\n### Emails\n\nThis library currently implements simple email checking against data breaches with the HaveIBeenPwned? API v3. It requires a [purchased api-key](https://haveibeenpwned.com/API/Key) in order to work.\n\nThe `Pwned.check_email/1` function returns the total number of times an email address has appeared in known data breaches, or an `\"email not pwned\"` message.\n\n### Passwords\n\nThis library uses [HaveIBeenPwned?](https://haveibeenpwned.com) to verify if a password has appeared in a data breach. \n\nIn order to protect the value of the source password being searched, the value is not sent through the network. Instead it uses a [k-Anonymity](https://en.wikipedia.org/wiki/K-anonymity) model that allows a [password to be searched for by partial hash](https://haveibeenpwned.com/API/v2#SearchingPwnedPasswordsByRange). This allows the first 5 characters of a SHA-1 password hash to be passed to the API. Then, it searches the results of the response for the presence of the source hash. If the source hash is not found, then the password does not exist in the data set.\n\nAdditionally, we implement padding to further protect the privacy of the password source hash in accordance with [password padding](https://haveibeenpwned.com/API/v3#PwnedPasswordsPadding) in API v3.\n\n## Table of Contents\n\n-   [Dependencies](#dependencies)\n-   [Install](#install)\n-   [Usage](#usage)\n-   [Changelog](#changelog)\n-   [Contributing](#contributing)\n-   [Further Reading](#further-reading)\n-   [License](#license)\n-   [Notice](#notice)\n-   [Special Thanks](#special-thanks)\n\n## Dependencies\n\nThis package requires [httpoison v1.8](https://hex.pm/packages/httpoison). If you have v1.7 in your `mix.lock` file, then you will need to update it to `1.8` to successfully run `mix deps.get`.\n\nIt also requires Elixir 1.11 to work. If you need functionality for earlier versions of Elixir, then we'd be happy to receive a PR.\n\n## Install\n\n**Recommended**\n\nThis package can be installed by adding `:pwned_coretheory` to your list of dependencies in `mix.exs`:\n\n```elixir\ndefp deps do\n  [\n    ...\n    {:pwned_coretheory, \"~\u003e 1.5\"},\n  ]\nend\n```\n\nThen, run `mix deps.get`. Additionally, run `mix deps.update pwned_coretheory` occasionally to ensure you have the latest release.\n\n**Running on master**\n\nIf you would like to run on the master branch, then update your dependencies as such:\n\n```elixir\ndefp deps do\n  [\n    ...\n    {:pwned_coretheory, github: \"coretheory/pwned_coretheory\"},\n  ]\nend\n```\n\n## Usage\n\nUsage is incredibly simple and straightforward. You can check if an\nemail or password has been pwned with calls to their respective\nfunctions.\n\nIn the case of checking for an email, you will need to have purchased\na [hibp-api-key](https://haveibeenpwned.com/API/Key).\n\nYou can use this library for password checking without the need for an\nAPI key. However, if this is the case, then keep in mind that not all\ntests will pass. If you do not need email checking, then we encourage\nyou to use the [pwned](https://github.com/thiamsantos/pwned) library\nby [Thiago Santos](https://github.com/thiamsantos).\n\n### Check for pwned passwords\n\nTo check whether a password has been pwned you can make a simple call to the `Pwned.check_password/1` function:\n\n```elixir\niex\u003e Pwned.check_password(\"P@ssw0rd\")\n      {:ok, 47205}\n\niex\u003e Pwned.check_password(\"Z76okiy2X1m5PFud8iPUQGqusShCJhg\")\n      {:ok, false}\n```\n\nWhen implementing in an application, we can use a straightforward `case` statement like this:\n\n```elixir\ncase Pwned.check_password(\"somepassword\") do\n  {:ok, false} -\u003e\n    IO.puts(\"Good news — no pwnage found!\")\n\n  {:ok, count} -\u003e\n    IO.puts(\"Oh, no! This password appeared #{count} times in data breaches.\")\n\n  :error -\u003e\n    IO.puts(\"Something went wrong.\")\nend\n```\n\n### Check for pwned emails\n\nFirst, let's make sure our `hibp-api-key` is ready to go.\n\n**Purchase your hibp-api-key and add it to an environment file**\n\nYou will first need to purchase a `hibp-api-key` from [haveibeenpwned?](https://haveibeenpwned.com/API/Key).\n\nThen, create a `.env` file at the root of your project (e.g. beside your `.gitignore`. Be sure to update\nyour `.gitignore` file to ignore environment files: `*.env`. \n\nOnce you are certain that you will not be pushing your environment files up to a source control repository,\nadd your purchased `hibp-api-key` to your `.env` file: `export HIBP_API_KEY=your_hibp_api_key`. Next, you'll\nwant to run `source .env` from your terminal.\n\nFor production, you'll want to have your `hibp-api-key` safely stored in your production host's environment\nvariables configuration with the key: `HIBP_API_KEY`.\n\nLastly, you can easily configure the `:user_agent` for the HIBP API, like so:\n\n```elixir\n# In your config.exs.\nconfig :pwned_coretheory,\n  user_agent: \"YourApp Pwned Client\"\n```\n\n_We highly recommend you set the configuration as it is good practice and informs the HaveIBeenPwned? service\nthat it is your application accessing the data and not a spammer or malicious account._\n\n**Checking emails**\n\nTo check whether an email has been pwned you can make a simple call to the `Pwned.check_email/1` function:\n\n```elixir\niex\u003e Pwned.check_email(\"test123@example.com\")\n    {:pwned_email, 4893554722}\n\niex\u003e Pwned.check_email(\"Z76okiy2X1m5PFud8iPUQGqusShCJhg@example.com\")\n    {:safe_email, \"email not pwned\"}\n```\n\nWhen implementing in an application, we can use a straightforward `case` statement like this:\n\n```elixir\ncase Pwned.check_email(\"test123@exmaple.com\") do\n  {:safe_email, message} -\u003e\n    IO.puts(message)\n\n  {:pwned_email, pwned_count} -\u003e\n    IO.puts(\"Ohh, sorry! This email has appeared #{pwned_count} times in data breaches.\")\n\n  {:error, message} -\u003e\n    IO.puts(\"An error occurred: \" \u003c\u003e message)\n  \n  :error -\u003e\n    IO.puts(\"Something went wrong.\")\nend\n```\n\n## Changelog\n\nSee the [changelog file](CHANGELOG.md).\n\n## Contributing\n\nSee the [contributing file](CONTRIBUTING.md).\n\n## Further Reading\n\nSee the [further reading file](FURTHER_READING.md).\n\n## License\n\n[Apache License, Version 2.0](LICENSE.md) © 2021 [Core Theory, Inc.](https://github.com/coretheory)\n\n## Notice\n\nThis is a modified version of the [pwned](https://github.com/thiamsantos/pwned) package © [@thiamsantos](https://github.com/thiamsantos).\n\n## Special thanks\n\nThis extension was built from the simple and wonderful package, [pwned](https://github.com/thiamsantos/pwned), by [Thiago Santos](https://github.com/thiamsantos). ♥\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoretheory%2Fpwned_coretheory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcoretheory%2Fpwned_coretheory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoretheory%2Fpwned_coretheory/lists"}