{"id":19198431,"url":"https://github.com/virgilsecurity/virgil-pythia-node","last_synced_at":"2025-05-09T01:17:17.580Z","repository":{"id":53811358,"uuid":"129751432","full_name":"VirgilSecurity/virgil-pythia-node","owner":"VirgilSecurity","description":"Virgil Pythia SDK allows developers to implement Pythia protocol to create breach-proof passwords, immune to offline and online attacks.","archived":false,"fork":false,"pushed_at":"2024-03-22T22:37:41.000Z","size":941,"stargazers_count":4,"open_issues_count":1,"forks_count":2,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-05-09T01:17:10.747Z","etag":null,"topics":["breach-proof-password","cryptography","encryption","nodejs","pythia","pythia-sdk","sdk","virgil-pythia"],"latest_commit_sha":null,"homepage":"https://developer.virgilsecurity.com/docs/javascript/use-cases/v5/breach-proof-password","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/VirgilSecurity.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-04-16T13:54:34.000Z","updated_at":"2023-09-30T23:49:46.000Z","dependencies_parsed_at":"2024-06-20T18:59:09.636Z","dependency_job_id":"7a7f2290-8404-4fe3-8d9c-a6a4d411a8bd","html_url":"https://github.com/VirgilSecurity/virgil-pythia-node","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VirgilSecurity%2Fvirgil-pythia-node","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VirgilSecurity%2Fvirgil-pythia-node/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VirgilSecurity%2Fvirgil-pythia-node/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VirgilSecurity%2Fvirgil-pythia-node/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VirgilSecurity","download_url":"https://codeload.github.com/VirgilSecurity/virgil-pythia-node/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253171289,"owners_count":21865299,"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":["breach-proof-password","cryptography","encryption","nodejs","pythia","pythia-sdk","sdk","virgil-pythia"],"created_at":"2024-11-09T12:21:56.801Z","updated_at":"2025-05-09T01:17:17.532Z","avatar_url":"https://github.com/VirgilSecurity.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e This README is for virgil-pythia v1.0.x. Check the [v0.2.7](https://github.com/VirgilSecurity/virgil-pythia-node/tree/v0.2.7) branch for virgil-pythia docs.\n\n# Virgil Pythia Node.js SDK\n[![npm](https://img.shields.io/npm/v/virgil-pythia.svg)](https://www.npmjs.com/package/virgil-pythia)\n[![Build Status](https://travis-ci.com/VirgilSecurity/virgil-pythia-node.svg?branch=master)](https://travis-ci.com/VirgilSecurity/virgil-pythia-node)\n[![GitHub license](https://img.shields.io/badge/license-BSD%203--Clause-blue.svg)](https://github.com/VirgilSecurity/virgil/blob/master/LICENSE)\n\n\n[Introduction](#introduction) | [SDK Features](#sdk-features) | [Install and configure SDK](#install-and-configure-sdk) | [Usage Examples](#usage-examples) | [Docs](#docs) | [Support](#support)\n\n## Introduction\n\n\u003ca href=\"https://developer.virgilsecurity.com/docs\"\u003e\u003cimg width=\"230px\" src=\"https://cdn.virgilsecurity.com/assets/images/github/logos/virgil-logo-red.png\" align=\"left\" hspace=\"10\" vspace=\"6\"\u003e\u003c/a\u003e\n[Virgil Security](https://virgilsecurity.com) provides an SDK which allows you to communicate with Virgil Pythia Service\nand implement Pythia protocol for the following use cases:.\n\n* *Breach-proof password*. Pythia is a technology that gives you a new, more secure mechanism that \"breach-proofs\" user\npasswords and lessens the security risks associated with weak passwords by providing cryptographic leverage for the\ndefender (by eliminating offline password cracking attacks), detection for online attacks, and key rotation to recover\nfrom stolen password databases.\n* *BrainKey*. User's Private Key which is based on user's password. BrainKey can be easily restored and is resistant to\nonline and offline attacks.\n\nIn both cases you get the mechanism which assures you that neither Virgil nor attackers know anything about user's\npassword.\n\n## SDK Features\n- communicate with Virgil Pythia Service\n- manage your Pythia application credentials\n- create, verify and update user's breach-proof password\n- generate user's BrainKey\n- use [Virgil Crypto Pythia library][_virgil_crypto_pythia]\n\n## Install and configure SDK\n\nInstall Pythia SDK with the following code:\n```bash\nnpm install virgil-pythia\n```\n\nYou will also need to install the `virgil-crypto`, `@virgilsecurity/pythia-crypto` and `virgil-sdk` packages.\n```bash\nnpm install virgil-crypto @virgilsecurity/pythia-crypto virgil-sdk\n```\n\n### Configure SDK\n\nThe library needs the following information from your [Virgil Dashboard][_dashboard] account:\n\n| Parameter | Description | Purpose |\n| --- | --- | --- |\n| API_KEY_ID | Id of the API Key | Used for JWT generation |\n| API_KEY | The private key of the API Key | Used for JWT generation |\n| APP_ID | Id of the Pythia App | Used for JWT generation |\n| PROOF_KEY | The Proof Key of the Pythia App | Used to verify the cryptographic proof that transformed password returned form service is correct |\n\nHere is an example of how to configure the library for work with Virgil Pythia Service:\n\n```javascript\n\nimport { initPythia, VirgilPythiaCrypto } from '@virgilsecurity/pythia-crypto';\nimport { initCrypto, VirgilCrypto, VirgilAccessTokenSigner } from 'virgil-crypto';\nimport { createPythia } from 'virgil-pythia';\nimport { JwtGenerator, GeneratorJwtProvider } from 'virgil-sdk';\n\nPromise.all([initCrypto(), initPythia()])\n  .then(() =\u003e {\n    const virgilCrypto = new VirgilCrypto();\n    const virgilPythiaCrypto = new VirgilPythiaCrypto();\n    const jwtGenerator = new JwtGenerator({\n      apiKey: crypto.importPrivateKey(process.env.API_KEY),\n      apiKeyId: process.env.API_KEY_ID,\n      appId: process.env.APP_ID,\n      accessTokenSigner: new VirgilAccessTokenSigner(crypto),\n    });\n    const accessTokenProvider = new GeneratorJwtProvider(jwtGenerator);\n    const pythia = createPythia({\n      virgilCrypto,\n      virgilPythiaCrypto,\n      accessTokenProvider,\n      proofKeys: [\n        process.env.PROOF_KEY,\n      ],\n    });\n  });\n```\n\n## Usage Examples\n\nVirgil Pythia SDK lets you create, verify and update user's breach-proof password using Virgil Crypto library.\n\nFirst of all, you need to set up your database to store users' breach-proof passwords. Create additional columns in your database for storing the following parameters:\n\u003ctable class=\"params\"\u003e\n\u003cthead\u003e\n    \u003ctr\u003e\n      \u003cth\u003eParameters\u003c/th\u003e\n      \u003cth\u003eType\u003c/th\u003e\n      \u003cth\u003eSize (bytes)\u003c/th\u003e\n      \u003cth\u003eDescription\u003c/th\u003e\n    \u003c/tr\u003e\n\u003c/thead\u003e\n\n\u003ctbody\u003e\n\u003ctr\u003e\n  \u003ctd\u003esalt\u003c/td\u003e\n  \u003ctd\u003eblob\u003c/td\u003e\n  \u003ctd\u003e32\u003c/td\u003e\n  \u003ctd\u003e Unique random string that is generated by Pythia SDK for each user\u003c/td\u003e\n\u003c/tr\u003e\n\n\u003ctr\u003e\n  \u003ctd\u003edeblindedPassword\u003c/td\u003e\n  \u003ctd\u003eblob \u003c/td\u003e\n  \u003ctd\u003e384 \u003c/td\u003e\n  \u003ctd\u003euser's breach-proof password\u003c/td\u003e\n\u003c/tr\u003e\n\n\u003ctr\u003e\n  \u003ctd\u003eversion\u003c/td\u003e\n  \u003ctd\u003eint \u003c/td\u003e\n  \u003ctd\u003e4 \u003c/td\u003e\n  \u003ctd\u003eVersion of your Pythia Application credentials. This parameter has the same value for all users unless you generate new Pythia credentials on Virgil Dashboard\u003c/td\u003e\n\u003c/tr\u003e\n\n\u003c/tbody\u003e\n\u003c/table\u003e\n\nNow we can start creating breach-proof passwords for users. Depending on the situation, you will use one of the\nfollowing Pythia SDK functions:\n- `createBreachProofPassword` is used to create a user's breach-proof password (e.g. during registration).\n- `verifyBreachProofPassword` is used to verify a user's breach-proof password (e.g. during authentication).\n\n### Create Breach-Proof Password\n\nUse this flow to create a new breach-proof password for a user.\n\n\u003e Remember, if you already have a database with user passwords, you don't have to wait until a user logs in into your\nsystem to implement Pythia.\nYou can go through your database and create breach-proof user passwords at any time.\n\nSo, in order to create a user's breach-proof password for a new database or existing one, take the following actions:\n- Take a user's password (or its hash or whatever you use) and pass it into the `createBreachProofPassword` function.\n- Pythia SDK will blind the password, send a request to Pythia Service to get a transformed blinded password and\nde-blind the transformed blinded password into a user's deblinded password (breach-proof password).\n\n```javascript\n// create a new Breach-proof password using user's password or its hash\npythia.createBreachProofPassword('USER_PASSWORD')\n  .then(bpPassword =\u003e {\n    // save the breach-proof password parameters into your database\n    console.log(bpPassword.salt.toString('base64')); // salt is a Buffer\n    console.log(bpPassword.deblindedPassword.toString('base64')); // deblindedPassword is a Buffer\n    console.log(bpPassword.version);\n  });\n```\n\nThe result of calling `createBreachProofPassword` is an object containing parameters mentioned previously (`salt`,\n`deblindedPassword`, `version`),\nsave these parameters into corresponding columns in your database.\n\nCheck that you've updated all database records and delete the now unnecessary column where users' passwords were\npreviously stored.\n\n### Verify Breach-Proof Password\n\nUse this flow when you need to verify that the user-provided plaintext password matches the breach-proof password stored\nin your database. You will have to pass their plaintext password into the `verifyBreachProofPassword` function:\n\n```javascript\nimport { BreachProofPassword } from 'virgil-pythia';\n\n// get user's Breach-proof password parameters from your users DB\n// ...\n// assuming user is the object representing your database record\nconst bpPassword = new BreachProofPassword(user.salt, user.deblindedPassword, user.version);\n\n// calculate user's Breach-proof password parameters\n// compare these parameters with parameters from your DB\npythia.verifyBreachProofPassword('USER_PASSWORD', bpPassword, false)\n  .then(verified =\u003e {\n    console.log(verified); // true if the plaintext password matches the stored one, otherwise false\n  });\n```\n\nThe difference between the `verifyBreachProofPassword` and `createBreachProofPassword` functions is that the\nverification of Pythia Service's response is optional in `verifyBreachProofPassword` function, which allows you\nto achieve maximum performance when processing data. You can turn on the proof step in `verifyBreachProofPassword`\nfunction if you have any suspicions that a user or Pythia Service were compromised.\n\n### Update breach-proof passwords\n\nThis step will allow you to use an `updateToken` in order to update users' breach-proof passwords in your database.\n\n\u003e Use this flow only if your database was COMPROMISED.\n\nHow it works:\n- Open your Pythia app page in Virgil Dashboard and press the \"My Database Was Compromised\" button.\n- Pythia Service generates a special updateToken and new Proof Key.\n- You then specify new Pythia Application credentials in the Pythia SDK on your Server side.\n- Then you use `updateBreachProofPassword` function to create new breach-proof passwords for your users.\n- Finally, you save the new breach-proof passwords into your database.\n\nHere is an example of using the `updateBreachProofPassword` function:\n```javascript\n//get previous user's breach-proof password parameters from a compromised DB\n\n// ...\n\n// set up an updateToken that you got on the Virgil Dashboard\n// update previous user's deblindedPassword and version, and save new one into your DB\n\nconst updatedBpPassword = pythia.updateBreachProofPassword('UT.1.2.UPDATE_TOKEN', bpPassword);\nconsole.log(updatedBpPassword.deblindedPassword.toString('base64'));\nconsole.log(updatedBpPassword.version);\n```\n\n### BrainKey\n\n*PYTHIA* Service can be used directly as a means to generate strong cryptographic keys based on user's **password** or other secret data. We call these keys the **BrainKeys**. Thus, when you need to restore a Private Key you use only user's Password and Pythia Service.\n\nIn order to create a user's BrainKey, go through the following operations:\n- Register your E2EE application on [Virgil Dashboard][_dashboard] and get your app credentials\n- Generate your API key or use available\n- Set up **JWT provider** using previously mentioned parameters (**App ID, API key, API key ID**) on the Server side\n- Generate JWT token with **user's identity** inside and transmit it to Client side (user's side)\n- On Client side set up **access token provider** in order to specify JWT provider\n- Setup BrainKey function with access token provider and pass user's password\n- Send BrainKey request to Pythia Service\n- Generate a strong cryptographic keypair based on a user's password or other user's secret\n\n\n#### Generate BrainKey based on user's password\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml lang=\"en\"\u003e\n\u003chead\u003e\n  \u003cmeta charset=\"UTF-8\"\u003e\n  \u003ctitle\u003eTitle\u003c/title\u003e\n  \u003cscript type=\"text/javascript\" src=\"https://unpkg.com/@virgilsecurity/pythia-crypto@^1.0.0/dist/browser.umd.js\"\u003e\u003c/script\u003e\n  \u003cscript type=\"text/javascript\" src=\"https://unpkg.com/virgil-crypto@^4.0.0/dist/browser.umd.js\"\u003e\u003c/script\u003e\n  \u003cscript type=\"text/javascript\" src=\"https://unpkg.com/virgil-pythia@^1.0.0/dist/browser.umd.js\"\u003e\u003c/script\u003e\n  \u003cscript type=\"text/javascript\" src=\"https://unpkg.com/virgil-sdk@^6.0.0/dist/virgil-sdk.browser.umd.js\"\u003e\u003c/script\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n\u003cscript\u003e\n  const fetchJwt = (context) =\u003e fetch('/virgil-access-token').then(response =\u003e {\n    if (!response.ok) {\n      throw new Error('Failed to get Virgil access token');\n    }\n    return response.text();\n  });\n\n  Promise.all([VirgilCrypto.initCrypto(), VirgilPythiaCrypto.initPythia()])\n    .then(() =\u003e {\n      const virgilCrypto = new VirgilCrypto.VirgilCrypto();\n      const virgilBrainKeyCrypto = new VirgilPythiaCrypto.VirgilBrainKeyCrypto();\n      const accessTokenProvider = new Virgil.CachingJwtProvider(fetchJwt);\n      const brainKey = VirgilPythia.createBrainKey({\n        virgilCrypto,\n        virgilBrainKeyCrypto,\n        accessTokenProvider,\n      });\n\n      // Generate default public/private keypair which is ED25519\n      // If you need to generate several BrainKeys for the same password, use different IDs.\n      brainKey.generateKeyPair('your password', 'optional_id')\n        .then(keyPair =\u003e {\n          console.log(keyPair);\n        });\n    });\n\u003c/script\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\n#### Generate BrainKey based on unique URL\nThe typical BrainKey implementation uses a password or concatenated answers to security questions to regenerate the user’s private key. But a unique session link generated by the system admin can also do the trick.\n\nThis typically makes the most sense for situations where it’s burdensome to require a password each time a user wants to send or receive messages, like single-session chats in a browser application.\n\nHere’s the general flow of how BrainKey can be used to regenerate a private key based on a unique URL:\n- When the user is ready to begin an encrypted messaging session, the application sends the user an SMS message\n- The SMS message contains a unique link like https://healthcare.app/?session=abcdef13803488\n- The string 'abcdef13803488' is used as a password for the private key regeneration\n- By clicking on the link, the user immediately establishes a secure session using their existing private key regenerated with Brainkey and does not need to input an additional password\n\nImportant notes for implementation:\n- The link is one-time use only. When the user clicks on the link, the original link expires and cannot be used again, and so a new link has to be created for each new chat session.\n- All URL links must be short-lived (recommended lifetime is 1 minute).\n- The SMS messages should be sent over a different channel than the one the user will be using for the secure chat session.\n- If you’d like to add additional protection to ensure that the person clicking the link is the intended chat participant, users can be required to submit their name or any other security question. This answer will need to be built in as part of the BrainKey password.\n\n```javascript\n...\nbrainKey.generateKeyPair('abcdef13803488', 'optional_user_ssn')\n  .then(keyPair =\u003e {\n    console.log(keyPair);\n  });\n...\n```\n\u003e Note! if you don't need to use additional parameters, like \"Optional User SSN\", you can just omit it: `brainKey.generateKeyPair('abcdef13803488')`\n\n\n\n## Docs\nVirgil Security has a powerful set of APIs, and the documentation below can get you started today.\n\n* [Breach-Proof Password][_pythia_use_case] Use Case\n* [Brain Key][_brain_key_use_case] Use Case\n* [The Pythia PRF Service](https://eprint.iacr.org/2015/644.pdf) - foundation principles of the protocol\n* [Virgil Security Documentation][_documentation]\n\n## License\n\nThis library is released under the [3-clause BSD License](LICENSE).\n\n## Support\nOur developer support team is here to help you. Find out more information on our [Help Center](https://help.virgilsecurity.com/).\n\nYou can find us on [Twitter](https://twitter.com/VirgilSecurity) or send us email support@VirgilSecurity.com.\n\nAlso, get extra help from our support team on [Slack](https://virgilsecurity.com/join-community).\n\n[_virgil_crypto_pythia]: https://github.com/VirgilSecurity/pythia\n[_brain_key_use_case]: https://developer.virgilsecurity.com/docs/use-cases/v1/brainkey\n[_pythia_use_case]: https://developer.virgilsecurity.com/docs/go/use-cases/v1/breach-proof-password\n[_documentation]: https://developer.virgilsecurity.com/\n[_dashboard]: https://dashboard.virgilsecurity.com/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvirgilsecurity%2Fvirgil-pythia-node","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvirgilsecurity%2Fvirgil-pythia-node","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvirgilsecurity%2Fvirgil-pythia-node/lists"}