{"id":19198427,"url":"https://github.com/virgilsecurity/virgil-sdk-javascript","last_synced_at":"2025-04-15T21:24:28.731Z","repository":{"id":3178699,"uuid":"48657403","full_name":"VirgilSecurity/virgil-sdk-javascript","owner":"VirgilSecurity","description":"Virgil Core SDK allows developers to get up and running with Virgil Cards Service API quickly and add end-to-end security to their new or existing digital solutions to become HIPAA and GDPR compliant and more.","archived":false,"fork":false,"pushed_at":"2023-01-27T18:20:11.000Z","size":24489,"stargazers_count":33,"open_issues_count":5,"forks_count":10,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-12T08:09:26.612Z","etag":null,"topics":["core-sdk","cryptography","encryption","end-to-end-encryption","gdpr","hipaa","pki","sdk"],"latest_commit_sha":null,"homepage":"https://virgilsecurity.com/","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":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-12-27T19:23:44.000Z","updated_at":"2025-02-21T13:14:58.000Z","dependencies_parsed_at":"2023-02-15T11:46:42.792Z","dependency_job_id":null,"html_url":"https://github.com/VirgilSecurity/virgil-sdk-javascript","commit_stats":null,"previous_names":[],"tags_count":81,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VirgilSecurity%2Fvirgil-sdk-javascript","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VirgilSecurity%2Fvirgil-sdk-javascript/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VirgilSecurity%2Fvirgil-sdk-javascript/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VirgilSecurity%2Fvirgil-sdk-javascript/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VirgilSecurity","download_url":"https://codeload.github.com/VirgilSecurity/virgil-sdk-javascript/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249155448,"owners_count":21221606,"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":["core-sdk","cryptography","encryption","end-to-end-encryption","gdpr","hipaa","pki","sdk"],"created_at":"2024-11-09T12:21:55.351Z","updated_at":"2025-04-15T21:24:28.709Z","avatar_url":"https://github.com/VirgilSecurity.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e This README is for Virgil SDK v6. If you're here for the previous version (v5.3.x), check the [v5.3.x branch](https://github.com/VirgilSecurity/virgil-sdk-javascript/tree/v5.3.x) for Virgil SDK v5.3.x docs.\n\n# Virgil Core SDK JavaScript \n\n[![npm](https://img.shields.io/npm/v/virgil-sdk.svg)](https://www.npmjs.com/package/virgil-sdk)\n[![Build status](https://img.shields.io/travis/VirgilSecurity/virgil-sdk-javascript.svg)](https://img.shields.io/travis/VirgilSecurity/virgil-sdk-javascript.svg)\n[![GitHub license](https://img.shields.io/badge/license-BSD%203--Clause-blue.svg)](https://github.com/VirgilSecurity/virgil/blob/master/LICENSE)\n[![API Reference](https://img.shields.io/badge/API%20Reference-virgil--sdk--javascript-green)](https://virgilsecurity.github.io/virgil-sdk-javascript/)\n\n[Introduction](#introduction) | [SDK Features](#sdk-features) | [Installation](#installation) | [Configure SDK](#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 [Virgil Security](https://virgilsecurity.com) provides a set of APIs for adding security to any application. In a few simple steps you can encrypt communications, securely store data, and ensure data integrity. Virgil Security products are available for desktop, embedded (IoT), mobile, cloud, and web applications in a variety of modern programming languages.\n\nThe Virgil Core SDK is a low-level library that allows developers to get up and running with [Virgil Cards Service API](https://developer.virgilsecurity.com/docs/platform/api-reference/cards-service/) quickly and add end-to-end security to their new or existing digital solutions.\n\nIn case you need additional security functionality for multi-device support, group chats and more, try our high-level [Virgil E3Kit framework](https://github.com/VirgilSecurity/awesome-virgil#E3Kit).\n\n## SDK Features\n\n- Communicate with [Virgil Cards Service](https://developer.virgilsecurity.com/docs/platform/api-reference/cards-service/)\n- Allow access for your application's users to Virgil Services using JWT\n- Manage users' public keys\n- Store private keys in IndexedDB as browser storage, filesystem for node.js or [Virgil key storage](https://github.com/VirgilSecurity/virgil-key-storage-rn) with React Native\n- Use Virgil [Crypto Library](https://github.com/VirgilSecurity/virgil-crypto-javascript)\n- Compatible with **post-quantum algorithms support** provided by Virgil Crypto Library: [Round5](https://round5.org/) (encryption) and [Falcon](https://falcon-sign.info/) (signature) \n\n## Installation\n\nThis module can be used both __server-side__ in a Node application, and __client-side__ in a web browser.\n\n#### On a server\n\nThe recommended way is to install from npm:\n\n```sh\nnpm install virgil-sdk\n```\n\nYou will also need to install the `virgil-crypto` package from npm, unless plan to use custom crypto\n```sh\nnpm install virgil-crypto\n```\n\n#### In the browser\n\nThe client-side SDK targets ECMAScript5+ compatible browsers. It is compatible with module bundlers like Rollup,\nWebpack and Browserify. If you're using those, you need to install from npm. It can be added to the html page directly\n via `script` tag as well.\n\nNote that the `virgil-crypto` script must also be added to the page.\n\n```html\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-sdk@^6.0.0/dist/virgil-sdk.browser.umd.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n\t// here you can use the global variables `Virgil` and `VirgilCrypto` as namespace objects,\n\t// containing all of `virgil-sdk` and `virgil-crypto` exports as properties\n\n    VirgilCrypto.initCrypto().then(() =\u003e {\n        // note that you cannot declare a variable named `crypto` in\n    \t// global scope (i.e. outside of any function) in browsers that\n    \t// implement Web Crypto API\n    \tconst virgilCrypto = new VirgilCrypto.VirgilCrypto();\n    \tconst virgilCardCrypto = new VirgilCrypto.VirgilCardCrypto(virgilCrypto);\n\n    \tconst jwtProvider = new Virgil.CachingJwtProvider(fetchVirgilJwt);\n    \tconst cardVerifier = new Virgil.VirgilCardVerifier(virgilCardCrypto);\n    \tconst cardManager = new Virgil.CardManager({\n    \t\tcardCrypto: virgilCardCrypto,\n    \t\taccessTokenProvider: jwtProvider,\n    \t\tcardVerifier: cardVerifier\n    \t});    \n    });\n\u003c/script\u003e\n```\n\n## Configure SDK\n\nThis section contains guides on how to set up Virgil Core SDK modules for authenticating users, managing Virgil Cards and storing private keys.\n\n### Set up authentication\n\nSet up user authentication with tokens that are based on the [JSON Web Token standard](https://jwt.io/) with some Virgil modifications.\n\nIn order to make calls to Virgil Services (for example, to publish user's Card on Virgil Cards Service), you need to have a JSON Web Token (\"JWT\") that contains the user's `identity`, which is a string that uniquely identifies each user in your application.\n\nCredentials that you'll need:\n\n|Parameter|Description|\n|--- |--- |\n|App ID|ID of your Application at [Virgil Dashboard](https://dashboard.virgilsecurity.com)|\n|App Key ID|A unique string value that identifies your account at the Virgil developer portal|\n|App Key|A Private Key that is used to sign API calls to Virgil Services. For security, you will only be shown the App Key when the key is created. Don't forget to save it in a secure location for the next step|\n\n#### Set up JWT provider on Client side\n\nUse these lines of code to specify which JWT generation source you prefer to use in your project:\n\n```javascript\n// client.js\n\nimport { CachingJwtProvider } from 'virgil-sdk';\n\nconst fetchJwt = () =\u003e fetch('/virgil-jwt', { credentials: 'same-origin' })\n    .then(response =\u003e response.text());\n\nconst jwtProvider = new CachingJwtProvider(fetchJwt);\n// pass jwtProvider as `accessTokenProvider` to the `CardManager` constructor\n```\n\n#### Generate JWT on Server side\n\nNext, you'll need to set up the `JwtGenerator` and generate a JWT using the Virgil SDK.\n\nHere is an example of how to generate a JWT:\n\n```javascript\n// server.js\n\nimport express from 'express';\nimport { initCrypto, VirgilCrypto, VirgilAccessTokenSigner } from 'virgil-crypto';\nimport { JwtGenerator } from 'virgil-sdk';\n\nasync function getJwtGenerator() {\n  await initCrypto();\n\n  const virgilCrypto = new VirgilCrypto();\n  // initialize JWT generator with your App ID and App Key ID you got in\n  // Virgil Dashboard and the `appKey` object you've just imported.\n  return new JwtGenerator({\n    appId: process.env.APP_ID,\n    apiKeyId: process.env.APP_KEY_ID,\n    // import your App Key that you got in Virgil Dashboard from string.\n    apiKey: virgilCrypto.importPrivateKey(process.env.APP_KEY),\n    // initialize accessTokenSigner that signs users JWTs\n    accessTokenSigner: new VirgilAccessTokenSigner(virgilCrypto),\n    millisecondsToLive:  20 * 60 * 1000 // JWT lifetime - 20 minutes (default)\n  });\n}\n\napp.get('/virgil-jwt', (req, res) =\u003e {\n  const generator = await generatorPromise;\n  const virgilJwtToken = generator.generateToken(req.user.identity);\n\n  res.json({ virgilToken: virgilJwtToken.toString() });\n});\n```\n\nFor this subsection we've created a sample backend that demonstrates how you can set up your backend to generate the JWTs. To set up and run the sample backend locally, head over to your GitHub repo of choice:\n\n[Node.js](https://github.com/VirgilSecurity/sample-backend-nodejs) | [Golang](https://github.com/VirgilSecurity/sample-backend-go) | [PHP](https://github.com/VirgilSecurity/sample-backend-php) | [Java](https://github.com/VirgilSecurity/sample-backend-java) | [Python](https://github.com/VirgilSecurity/virgil-sdk-python/tree/master#sample-backend-for-jwt-generation)\n and follow the instructions in README.\n \n### Set up Card Verifier\n\nVirgil Card Verifier helps you automatically verify signatures of a user's Card, for example when you get a Card from Virgil Cards Service.\n\nBy default, `VirgilCardVerifier` verifies only two signatures - those of a Card owner and Virgil Cards Service.\n\nSet up `VirgilCardVerifier` with the following lines of code:\n\n```javascript\nimport { initCrypto, VirgilCrypto, VirgilCardCrypto } from 'virgil-crypto';\nimport { VirgilCardVerifier } from 'virgil-sdk';\n\n(async function() {\n\t// initialize Crypto library\n\tawait initCrypto();\n\tconst cardCrypto = new VirgilCardCrypto(new VirgilCrypto());\n\tconst cardVerifier = new VirgilCardVerifier(cardCrypto);\n})();\n```\n\n### Set up Card Manager\n\nThis subsection shows how to set up a Card Manager module to help you manage users' public keys.\n\nWith Card Manager you can:\n- specify an access Token (JWT) Provider.\n- specify a Card Verifier used to verify signatures of your users, your App Server, Virgil Services (optional).\n\nUse the following lines of code to set up the Card Manager:\n\n```javascript\nimport { CardManager } from 'virgil-sdk';\n\n// initialize cardManager and specify accessTokenProvider, cardVerifier\nconst cardManager = new CardManager({\n  cardCrypto: cardCrypto,\n  accessTokenProvider: accessTokenProvider,\n  cardVerifier: cardVerifier\n});\n```\n\n### Set up Key Storage for private keys\n\nThis subsection shows how to set up a `PrivateKeyStorage` using Virgil SDK in order to save private keys after their generation.\n\nHere is an example of how to set up the `PrivateKeyStorage` class:\n\n```javascript\nimport { initCrypto, VirgilCrypto, VirgilPrivateKeyExporter } from 'virgil-crypto';\nimport { PrivateKeyStorage } from 'virgil-sdk';\n\n(async function() {\n\t// initialize Virgil Crypto library\n\tawait initCrypto();\n\n\tconst virgilCrypto = new VirgilCrypto();\n\tconst privateKeyExporter = new VirgilPrivateKeyExporter(\n\t\tvirgilCrypto,\n\t\t// if provided, will be used to encrypt the key bytes before exporting\n\t\t// and decrypt before importing.\n\t\t'[OPTIONAL_PASSWORD_TO_ENCRYPT_THE_KEYS_WITH]'\n\t);\n\t// Generate a private key\n\tconst keyPair = virgilCrypto.generateKeys();\n\n\tconst privateKeyStorage = new PrivateKeyStorage(privateKeyExporter);\n\n\t// Store the private key with optional metadata (i.e. the PrivateKeyEntry)\n\tawait privateKeyStorage.store('my private key', keyPair.privateKey, { optional: 'data' });\n\n\t// Load the private key entry\n\tconst privateKeyEntry = await privateKeyStorage.load('my private key');\n\n\tif (privateKeyEntry === null) {\n\t\treturn;\n\t}\n\n\tconsole.log(privateKeyEntry.privateKey); // VirgilPrivateKey instance\n\tconsole.log(privateKeyEntry.meta); // { optional: 'data' }\n\n\tconst privateKey = privateKeyEntry.privateKey;\n\n\t// Use the privateKey in virgilCrypto operations\n\n\t// Delete a private key\n\tawait privateKeyStorage.delete('my private key');\n\n\tconsole.log('Private key has been removed');\n})();\n```\n\n## Usage Examples\n\nBefore you start practicing with the usage examples, make sure that the SDK is configured. See the [Configure SDK](#configure-sdk) section for more information.\n\n### Generate and publish Virgil Cards at Cards Service\n\nUse the following lines of code to create a user's Card with a public key inside and publish it at Virgil Cards Service:\n\n```javascript\nimport { initCrypto, VirgilCrypto, VirgilCardCrypto, VirgilPrivateKeyExporter } from 'virgil-crypto';\nimport { CachingJwtProvider, CardManager, PrivateKeyStorage, VirgilCardVerifier } from 'virgil-sdk';\n\n(async function() {\n    await initCrypto();\n\n\tconst virgilCrypto = new VirgilCrypto();\n\tconst cardCrypto = new VirgilCardCrypto(virgilCrypto);\n\n\tconst jwtProvider = new CachingJwtProvider(fetchVirgilJwt);\n\tconst cardVerifier = new VirgilCardVerifier(cardCrypto);\n\tconst cardManager = new CardManager({\n\t\tcardCrypto: cardCrypto,\n\t\taccessTokenProvider: jwtProvider,\n\t\tcardVerifier: cardVerifier\n\t});\n\tconst privateKeyStorage = new PrivateKeyStorage(\n\t\tnew VirgilPrivateKeyExporter(virgilCrypto)\n\t);\n\n\t// Generate a key pair\n\tconst keyPair = virgilCrypto.generateKeys();\n\n\t// Store the private key\n\tawait privateKeyStorage.store('alice_private_key', keyPair.privateKey);\n\n\t// Publish user's card on the Cards Service\n\tconst card = await cardManager.publishCard({\n\t\tprivateKey: keyPair.privateKey,\n\t\tpublicKey: keyPair.publicKey,\n\t\tidentity: 'alice@example.com'\n\t});\n})();\n\nasync function fetchVirgilJwt (context) {\n\t// assuming your backend server is serving Virgil JWT tokens in plaintext\n\t// at /virgil-access-token endpoint\n\tconst response = await fetch('/virgil-access-token');\n\tif (!response.ok) {\n\t\tthrow new Error('Failed to get Virgil Access Token');\n\t}\n\n\treturn await response.text();\n}\n```\n\n### Sign then encrypt data\n\nVirgil Core SDK allows you to use a user's private key and their Virgil Cards to sign and encrypt any kind of data.\n\nIn the following example, we load a private key from a customized key storage and get recipient's Card from the Virgil Cards Service. Recipient's Card contains a public key which we will use to encrypt the data and verify a signature.\n\n```javascript\nimport { initCrypto, VirgilCrypto, VirgilPrivateKeyExporter } from 'virgil-crypto';\nimport { PrivateKeyStorage } from 'virgil-sdk';\n\n(async function() {\n\tawait initCrypto();\n\n\tconst virgilCrypto = new VirgilCrypto();\n\tconst privateKeyStorage = new PrivateKeyStorage(\n\t\tnew VirgilPrivateKeyExporter(virgilCrypto)\n\t);\n\n\t// Load the private key\n\tconst alicePrivateKey = await privateKeyStorage.load('alice_private_key');\n\tif (alicePrivateKey === null) {\n\t\tconsole.log('Private key named \"alice_private_key\" does not exist');\n\t\treturn;\n\t}\n\n\tconst cards = await cardManager.searchCards('bob@example.com');\n\tif (cards.length === 0) {\n\t\tconsole.log('Virgil Card with identity \"bob@example.com\" does not exist');\n\t\treturn;\n\t}\n\n\tconst messageToEncrypt = 'Hello, Bob!';\n\tconst bobPublicKeys = cards.map(card =\u003e card.publicKey);\n\tconst encryptedMessage = virgilCrypto.signThenEncrypt(messageToEncrypt, alicePrivateKey, bobPublicKeys);\n\tconsole.log(encryptedMessage.toString('base64'));\n})();\n```\n\n### Decrypt data and verify signature\n\nOnce the user receives the signed and encrypted message, they can decrypt it with their own private key and verify the signature with the sender's Card:\n\n```javascript\nimport { initCrypto, VirgilCrypto, VirgilPrivateKeyExporter } from 'virgil-crypto';\nimport { PrivateKeyStorage } from 'virgil-sdk';\n\n(async function() {\n\tawait initCrypto();\n\n\tconst virgilCrypto = new VirgilCrypto();\n\tconst privateKeyStorage = new PrivateKeyStorage(\n\t\tnew VirgilPrivateKeyExporter(virgilCrypto)\n\t);\n\n\t// Load the private key\n\tconst bobPrivateKey = await privateKeyStorage.load('bob_private_key');\n\tif (bobPrivateKey === null) {\n\t\tconsole.log('Private key named \"bob_private_key\" does not exist');\n\t\treturn;\n\t}\n\n\tconst cards = await cardManager.searchCards('alice@example.com');\n\tif (cards.length === 0) {\n\t\tconsole.log('Virgil Card with identity \"alice@example.com\" does not exist');\n\t\treturn;\n\t}\n\n\tconst alicePublicKeys = cards.map(card =\u003e card.publicKey);\n\tconst decryptedMessage = virgilCrypto.decryptThenVerify(encryptedMessage, bobPrivateKey, alicePublicKeys);\n\tconsole.log(decryptedMessage.toString());\n})();\n```\n\n### Get Card by its ID\n\nUse the following lines of code to get a user's card from Virgil Cloud by its ID:\n\n```javascript\ncardManager.getCard('f4bf9f7fcbedaba0392f108c59d8f4a38b3838efb64877380171b54475c2ade8')\n.then(card =\u003e {\n    console.log('Got: ', card);\n});\n```\n\n### Get Card by user's identity\n\nFor a single user, use the following lines of code to get a user's Card by a user's `identity`:\n\n```javascript\ncardManager.searchCards('alice@example.com')\n.then(cards =\u003e {\n    cards.map(card =\u003e console.log(card.id));\n});\n```\n\n## Docs\n\n* [Developer Documentation](https://developer.virgilsecurity.com/)\n* [API Reference](https://virgilsecurity.github.io/virgil-sdk-javascript/)\n\n## License\n\nThis library is released under the [3-clause BSD License](LICENSE).\n\n## Support\n\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvirgilsecurity%2Fvirgil-sdk-javascript","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvirgilsecurity%2Fvirgil-sdk-javascript","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvirgilsecurity%2Fvirgil-sdk-javascript/lists"}