Check My Secrets

NodeJS script checking whether any of the passwords used online are compromised.

It uses the ';--have i been pwned? V3 API, specifically the GET https://api.pwnedpasswords.com/range/{first 5 hash chars} to determine if a password is compromised.

Requirements

• Node >= v17

Getting started

1. Clone the repo ☝️, for example:

git clone https://github.com/koalyptus/check-my-secrets.git

2. Install all the requirements:

npm install

3. Run the setup command to create your global config folder and a default .env file:

npm run setup

This will create a folder at ~/.check-my-secrets and place a default .env file inside it. You can then open this .env file in your preferred text editor to customize your PWDS_KEY and PWDS_SEPARATOR.

⚠️ The CLI loads configuration from the single global location: ~/.check-my-secrets/.env. If this file is not present, or if PWDS_KEY or PWDS_SEPARATOR are not defined within it, the script will fall back to the built-in defaults:

checkmysecrets.pwds
,

Security notes:

• PWDS_KEY is only a keyring identifier (safe to store). Do NOT store the actual encryption key or plaintext secrets in this file.
• Restrict file permissions so only your user can read it (on Unix: chmod 600 ~/.check-my-secrets/.env).
• On Windows, ensure the file ACL only grants access to your user account.

4. Manage your passwords using the following commands:

   • Add a password:

     npm run secrets:add <your-password>

     This will add <your-password> to your keyring. If the password already exists, it will not be added again.

   • List all stored passwords:

     npm run secrets:list

     This will display a table of your stored passwords after an interactive confirmation.

   • Delete a password:

     npm run secrets:delete <password-to-delete>

     This will remove <password-to-delete> from your keyring.

   • Check all your passwords:

     npm start

     or

     npm run secrets:check

     This command will check the integrity of all passwords stored in your keyring. Depending on your OS, a notification will pop up similar to below:

Development

Setup for Local Development

To use the CLI commands globally while developing, link the package locally:

npm link

This creates symlinks for all CLI commands, making them available system-wide:

• check-my-secrets - Check all stored passwords
• secrets-add - Add a password
• secrets-check - Check all stored passwords
• secrets-delete - Delete a password
• secrets-list - List all passwords

Example:

check-my-secrets
secrets-add MyPassword123
secrets-list
secrets-delete MyPassword123

To unlink when done:

npm unlink -g check-my-secrets

Running Tests

Run all tests:

npm test

Run specific test suite:

npm test -- tests/lib/config.test.js

Test coverage:

npm run test:coverage

Code Quality

Format code:

npm run format:fix

Lint code:

npm run lint