Skip to content
Virgil Pythia SDK allows developers to implement Pythia protocol to create breach-proof passwords, immune to offline and online attacks.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
src fix errors export Oct 12, 2018
.editorconfig implement crypto operations Apr 24, 2018
.env.example add ability to test with fake server Apr 27, 2018
.eslintrc.js add eslint Oct 12, 2018
.travis.yml chore: setup ci Jun 26, 2018 Updated Slack link Jan 23, 2019

Virgil Pythia Node.js SDK

npm Build Status GitHub license

Introduction | SDK Features | Install and configure SDK | Usage Examples | Docs | Support


Virgil Security provides an SDK which allows you to communicate with Virgil Pythia Service and implement Pythia protocol for the following use cases:.

  • Breach-proof password. Pythia is a technology that gives you a new, more secure mechanism that "breach-proofs" user passwords and lessens the security risks associated with weak passwords by providing cryptographic leverage for the defender (by eliminating offline password cracking attacks), detection for online attacks, and key rotation to recover from stolen password databases.
  • BrainKey. User's Private Key which is based on user's password. BrainKey can be easily restored and is resistant to online and offline attacks.

In both cases you get the mechanism which assures you that neither Virgil nor attackers know anything about user's password.

SDK Features

  • communicate with Virgil Pythia Service
  • manage your Pythia application credentials
  • create, verify and update user's breach-proof password
  • generate user's BrainKey
  • use Virgil Crypto Pythia library

Install and configure SDK

The Virgil Pythia Node.js SDK is provided as npm package named virgil-pythia. This package is compatible with Node.js 6 or newer.

Install Pythia SDK with the following code:

npm install virgil-pythia

You will also need to install the virgil-crypto and virgil-sdk packages separately:

npm install virgil-crypto virgil-sdk

Configure SDK

The library needs the following information from your Virgil Dashboard]_dashboard account:

Parameter Description Purpose
API_KEY_ID Id of the API Key Used for JWT generation
API_KEY The private key of the API Key Used for JWT generation
APP_ID Id of the Pythia App Used for JWT generation
PROOF_KEY The Proof Key of the Pythia App Used to verify the cryptographic proof that transformed password returned form service is correct

Here is an example of how to configure the library for work with Virgil Pythia Service:

import { VirgilCrypto, VirgilPythiaCrypto, VirgilAccessTokenSigner } from 'virgil-crypto/dist/virgil-crypto-pythia.cjs';
import { JwtGenerator, GeneratorJwtProvider } from 'virgil-sdk';
import { createPythia } from 'virgil-pythia';

const virgilCrypto = new VirgilCrypto();
const virgilPythiaCrypto = new VirgilPythiaCrypto();

const jwtGenerator = new Virgil.JwtGenerator({
	apiKey: virgilCrypto.importPrivateKey(process.env.API_KEY),
	apiKeyId: process.env.API_KEY_ID,
	appId: process.env.APP_ID,
	accessTokenSigner: new VirgilAccessTokenSigner(virgilCrypto)

const pythia = VirgilPythia.createPythia({
	accessTokenProvider: new GeneratorJwtProvider(jwtGenerator),
	proofKeys: [

Usage Examples

Virgil Pythia SDK lets you create, verify and update user's breach-proof password using Virgil Crypto library.

First 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:

Parameters Type Size (bytes) Description
salt blob 32 Unique random string that is generated by Pythia SDK for each user
deblindedPassword blob 384 user's breach-proof password
version int 4 Version of your Pythia Application credentials. This parameter has the same value for all users unless you generate new Pythia credentials on Virgil Dashboard

Now we can start creating breach-proof passwords for users. Depending on the situation, you will use one of the following Pythia SDK functions:

  • createBreachProofPassword is used to create a user's breach-proof password (e.g. during registration).
  • verifyBreachProofPassword is used to verify a user's breach-proof password (e.g. during authentication).

Create Breach-Proof Password

Use this flow to create a new breach-proof password for a user.

Remember, if you already have a database with user passwords, you don't have to wait until a user logs in into your system to implement Pythia. You can go through your database and create breach-proof user passwords at any time.

So, in order to create a user's breach-proof password for a new database or existing one, take the following actions:

  • Take a user's password (or its hash or whatever you use) and pass it into the createBreachProofPassword function.
  • Pythia SDK will blind the password, send a request to Pythia Service to get a transformed blinded password and de-blind the transformed blinded password into a user's deblinded password (breach-proof password).
// create a new Breach-proof password using user's password or its hash
	.then(bpPassword => {
		// save the breach-proof password parameters into your database
        console.log(bpPassword.salt.toString('base64')); // salt is a Buffer
        console.log(bpPassword.deblindedPassword.toString('base64')); // deblindedPassword is a Buffer

The result of calling createBreachProofPassword is an object containing parameters mentioned previously (salt, deblindedPassword, version), save these parameters into corresponding columns in your database.

Check that you've updated all database records and delete the now unnecessary column where users' passwords were previously stored.

Verify Breach-Proof Password

Use this flow when you need to verify that the user-provided plaintext password matches the breach-proof password stored in your database. You will have to pass their plaintext password into the verifyBreachProofPassword function:

import { BreachProofPassword } from 'virgil-pythia';

// get user's Breach-proof password parameters from your users DB
// ...
// assuming user is the object representing your database record
const bpPassword = new BreachProofPassword(user.salt, user.deblindedPassword, user.version);

// calculate user's Breach-proof password parameters
// compare these parameters with parameters from your DB
pythia.verifyBreachProofPassword('USER_PASSWORD', bpPassword, false)
	.then(verified => {
		console.log(verified); // true if the plaintext password matches the stored one, otherwise false

The difference between the verifyBreachProofPassword and createBreachProofPassword functions is that the verification of Pythia Service's response is optional in verifyBreachProofPassword function, which allows you to achieve maximum performance when processing data. You can turn on the proof step in verifyBreachProofPassword function if you have any suspicions that a user or Pythia Service were compromised.

Update breach-proof passwords

This step will allow you to use an updateToken in order to update users' breach-proof passwords in your database.

Use this flow only if your database was COMPROMISED.

How it works:

  • Open your Pythia app page in Virgil Dashboard and press the "My Database Was Compromised" button.
  • Pythia Service generates a special updateToken and new Proof Key.
  • You then specify new Pythia Application credentials in the Pythia SDK on your Server side.
  • Then you use updateBreachProofPassword function to create new breach-proof passwords for your users.
  • Finally, you save the new breach-proof passwords into your database.

Here is an example of using the updateBreachProofPassword function:

//get previous user's breach-proof password parameters from a compromised DB

// ...

// set up an updateToken that you got on the Virgil Dashboard
// update previous user's deblindedPassword and version, and save new one into your DB

const updatedBpPassword = pythia.updateBreachProofPassword('UT.1.2.UPDATE_TOKEN', bpPassword);


PYTHIA Service can be used directly as a means to generate strong cryptographic keys based on user's password. We call these keys the BrainKeys. Thus when you need to restore a Private Key you use only user's Password and Pythia Service.

Generate BrainKey

Use this flow to generate a new BrainKey for a user.

In order to create a user's BrainKey, go through the following operations:

  • Register your E2EE application on Virgil Dashboard and get your app credentials
  • Generate your API key or use available
  • Set up JWT provider using previously mentioned parameters (App ID, API key, API key ID) on the Server side
  • Generate JWT token with user's identity inside and transmit it to Client side (user's side)
  • On Client side set up access token provider to call out to your backend to get the JWT.
  • Setup BrainKey function with access token provider and pass user's password
  • Send BrainKey request to Pythia Service
  • Generate keypair based on BrainKey that you've got from Pythia Service and create user's Card
  • Pass user's Card to cardManager
  • Publish user's Card that is related to the BrainKey
<!DOCTYPE html>
<html lang="en">
	<meta charset="UTF-8">
	<script src=""></script>
	<script src=""></script>
	<script src=""></script>
	const fetchJwt = (context) => fetch('/virgil-access-token').then(response => {
		if (!response.ok) {
		  throw new Error('Failed to get Virgil access token');
		return response.text();

	const virgilCrypto = new VirgilCrypto.VirgilCrypto();
	const virgilPythiaCrypto = new VirgilCrypto.VirgilPythiaCrypto();
	const virgilCardCrypto = new VirgilCardCrypto(virgilCrypto);

	const jwtProvider = new Virgil.CachingJwtProvider(fetchJwt);
	const cardManager = new Virgil.CardManager({
		cardCrypto: virgilCardCrypto,
		accessTokenProvider: jwtProvider,
		cardVerifier: new Virgil.VirgilCardVerifier(virgilCardCrypto)

	const brainKey = VirgilPythia.createBrainKey({
		accessTokenProvider: jwtProvider

		.then(keyPair => cardManager.publishCard(keyPair))
		.then(card => console.log('Published card', card));
		.catch(err => console.log(err));


Virgil Security has a powerful set of APIs, and the documentation below can get you started today.


This library is released under the 3-clause BSD License.


Our developer support team is here to help you. Find out more information on our Help Center.

You can find us on Twitter or send us email

Also, get extra help from our support team on Slack.

You can’t perform that action at this time.