{"id":13454568,"url":"https://github.com/buttercup/buttercup-core","last_synced_at":"2025-05-16T07:05:52.187Z","repository":{"id":44703444,"uuid":"42001175","full_name":"buttercup/buttercup-core","owner":"buttercup","description":":tophat: The mighty NodeJS password vault","archived":false,"fork":false,"pushed_at":"2025-03-04T08:59:43.000Z","size":5361,"stargazers_count":475,"open_issues_count":33,"forks_count":57,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-05-08T06:34:59.432Z","etag":null,"topics":["buttercup","credentials","datasource","encryption","hacktoberfest","nodejs","nodejs-password-vault","password","password-manager","password-store","password-vault","passwords"],"latest_commit_sha":null,"homepage":"http://buttercup.pw/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/buttercup.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2015-09-06T12:05:21.000Z","updated_at":"2025-04-14T18:47:17.000Z","dependencies_parsed_at":"2022-08-12T11:21:28.570Z","dependency_job_id":"a48b4b4e-6f26-437a-b2ce-0f0a2b595193","html_url":"https://github.com/buttercup/buttercup-core","commit_stats":{"total_commits":1686,"total_committers":12,"mean_commits":140.5,"dds":0.07058125741399768,"last_synced_commit":"5aac50d9cfab453f7df80196f7ffb031a4985f9d"},"previous_names":[],"tags_count":249,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buttercup%2Fbuttercup-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buttercup%2Fbuttercup-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buttercup%2Fbuttercup-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buttercup%2Fbuttercup-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/buttercup","download_url":"https://codeload.github.com/buttercup/buttercup-core/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253775074,"owners_count":21962284,"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":["buttercup","credentials","datasource","encryption","hacktoberfest","nodejs","nodejs-password-vault","password","password-manager","password-store","password-vault","passwords"],"created_at":"2024-07-31T08:00:55.480Z","updated_at":"2025-05-16T07:05:47.664Z","avatar_url":"https://github.com/buttercup.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n  \u003cbr/\u003e\n  \u003cimg src=\"https://cdn.rawgit.com/buttercup-pw/buttercup-assets/054fc0fa/badge/core.svg\" alt=\"Buttercup Core\"\u003e\n  \u003cbr/\u003e\n  \u003cbr/\u003e\n  \u003cbr/\u003e\n\u003c/h1\u003e\n\n# Buttercup core library\n\nA NodeJS secrets vault.\n\n[![Buttercup](https://cdn.rawgit.com/buttercup-pw/buttercup-assets/6582a033/badge/buttercup-slim.svg)](https://buttercup.pw) [![npm](https://img.shields.io/npm/dt/buttercup.svg)](https://www.npmjs.com/package/buttercup) [![npm version](https://badge.fury.io/js/buttercup.svg)](https://badge.fury.io/js/buttercup) ![node min version](https://img.shields.io/badge/node-%3E%3D%2014.x-lightgrey.svg) [![security](https://img.shields.io/badge/Security-As%20you%20wish-green.svg)](https://en.wikipedia.org/wiki/The_Princess_Bride_(film)) [![encryption](https://img.shields.io/badge/Encryption-AES%20256%20CBC%2FGCM-red.svg)](https://tools.ietf.org/html/rfc3602)\n\n![Tests status](https://github.com/buttercup/buttercup-core/actions/workflows/test.yml/badge.svg)\n\n[![NPM](https://nodei.co/npm/buttercup.png)](https://www.npmjs.com/package/buttercup)\n\n---\n\n⚠️ **Project Closure** ⚠️\n\nThe Buttercup project has come to an end, and these repositories are in transition to becoming public archives. No public-facing resources will be removed, wherever possible. Please do not create issues or PRs - they will unfortunately be ignored. Discussion can be found [here](https://github.com/buttercup/buttercup-desktop/discussions/1395), and explanation [here](https://gist.github.com/perry-mitchell/43ebfcec4d874b77a704be1d4f2262e6).\n\n---\n\n## About\n\nButtercup is a JavaScript password manager for NodeJS and the browser (though you can also see it used on platforms like [React Native](https://github.com/buttercup/buttercup-mobile)). It's based around the concept of a **Vault** and its secret **Entry** items (a login, credit card etc.). Entries are then separated into **Group** containers that make organising vaults a little easier.\n\nBecause Buttercup is designed first and foremost to be consumed by users in some application, **VaultManager** and **VaultSource** constructs are provided to allow for easy control over several vaults in a somewhat shared environment. A vault manager provides easy-to-use methods to perform dehydration and rehydration (storage in serialised form) of vaults to some secure storage (files, remote datasources etc.).\n\nButtercup can save and load vaults that are stored locally, in cloud service providers like Dropbox or Google Drive, or in a cloud service's WebDAV-enabled storage. It does this by providing a **Datasource** construct for each provider.\n\nBecause Buttercup can be consumed in some interesting and varied environments, serialisation tools called **facades** are provided to allow for greater flexibility when working with vault data structures. Facades provide a way to move data around without _classes_, converting vaults to and from JSON objects. Facades are used when attaching vaults to user interfaces like with the [Buttercup UI library](https://github.com/buttercup/ui).\n\n### Features\n\nThe core of the system, this **Buttercup Core**, boasts a few awesome features:\n\n * Merge-able vault contents\n * History for back-tracking to previous passwords etc.\n * File attachments (encrypted)\n * AES CBC encryption\n * GZip compression\n * NodeJS and Browser support\n\nThis library also supports a variety of datasources for loading from and saving to:\n\n * WebDAV\n * [Dropbox](https://www.dropbox.com/)\n * [Google Drive](https://www.google.com/drive/)\n * Local files\n * In-memory (testing, prototyping)\n\nCheck out the [changelog](https://github.com/buttercup/buttercup-core/blob/master/CHANGELOG.md).\n\n## Installation\n\nTo use Buttercup in a NodeJS environment, you can simply install and require it:\n\n```shell\nnpm install buttercup --save\n```\n\nIn a Node environment, for example:\n\n```javascript\nconst { Vault } = require(\"buttercup\");\n```\n\nOr for Typescript:\n\n```typescript\nimport { Vault } from \"buttercup\";\n```\n\nIn a _web_ environment, use the following:\n\n```javascript\nimport { Vault } from \"buttercup/web\";\n```\n\nButtercup core is ESM - you must either import it in a project that is also ESM, or use a build tool like Webpack.\n\n_Buttercup core supports Node version 14 and up. For older Node versions use v6 and earlier._\n\n## Usage\n\nButtercup uses `Vault`s, `Group`s and `Entry`s to manipulate data in a _workspace_-like environment. These 3 constructs have no knowledge of encryption or storage, and simply provide interfaces for working with the data structures.\n\nTo manage vaults, their storage and their states in a higher-level manner more appropriate for building applications, check out the `VaultManager` and `VaultSource` constructs.\n\nTo get started, we should create a new Vault:\n\n```javascript\nimport { Vault, init } from \"buttercup\";\n\n// Initialise environment\ninit();\n\n// Create an empty vault\nconst vault1 = new Vault();\n\n// Create aa vault with \"General\" and \"Trash\" groups\nconst vault2 = Vault.createWithDefaults();\n```\n\nThe `init()` function call is used to initialise the environment (performs the same function as `@buttercup/app-env` used to). It is required for Buttercup to work. It can be called more than once without effect.\n\nEntries can't be added directly to a Vault, but can be to Groups. Creating Groups and Entries is trivial:\n\n```javascript\nconst vault = Vault.createWithDefaults();\nconst myGroup = vault.createGroup(\"My Group\");\nconst myEntry = myGroup.createEntry(\"My Entry\");\n```\n\nEvery command on Vaults, Groups and Entries **modifies the Vault instance**, but does not save it to storage. There is no command or need to commit any data - each instance links back to the original Vault. Vaults are saved and loaded using Datasources:\n\n```javascript\nimport { Credentials, FileDatasource, Vault, init } from \"buttercup\";\n\ninit();\n\nconst datasourceCredentials = Credentials.fromDatasource({\n    path: \"./user.bcup\"\n}, \"masterPassword!\");\nconst fileDatasource = new FileDatasource(datasourceCredentials);\nconst vault = Vault.createWithDefaults();\nvault\n    .createGroup(\"Websites\")\n        .createEntry(\"My bank\")\n            .setProperty(\"username\", \"user-name\")\n            .setProperty(\"password\", \"s3cureP4$$\");\n\nconst vaultCredentials = Credentials.fromPassword(\"masterPassword!\");\nawait fileDatasource.save(vault.format.history, vaultCredentials);\n```\n\nLater:\n\n```javascript\nconst datasourceCredentials = Credentials.fromDatasource({\n    path: \"./user.bcup\"\n}, \"masterPassword!\");\nconst fileDatasource = new FileDatasource(datasourceCredentials);\n\nfileDatasource\n    .load(datasourceCredentials)\n    .then(Vault.createFromHistory)\n    .then(vault =\u003e {\n        // ...\n    });\n```\n\nUsing just a datasource is not recommended as saving and loading is quite low-level and cumbersome. Check the [browser extension](https://github.com/buttercup/buttercup-browser-extension) or [desktop application](https://github.com/buttercup/buttercup-desktop) for examples of how to use the `VaultManager` and other helpful classes.\n\n### Development\n\nTo develop Buttercup Core, clone the repository on a Linux or Mac OS machine. Ensure that you're running NodeJS version 16/18. Install all dependencies by running `npm install` in the project directory. Run the tests to ensure everything is functioning correctly: `npm test`.\n\n## Vault Formats\n\nButtercup currently supports [2 concurrent vault formats](VAULT_FORMAT.md), as it is in the process of transitioning from **Format A** (legacy) to **Format B**. You can switch the operational format by doing the following:\n\n```javascript\nconst { VaultFormatB, init, setDefaultFormat } = require(\"buttercup\");\n\ninit();\n\nsetDefaultFormat(VaultFormatB);\n```\n\nButtercup will automatically transition to using Format B as the default in some weeks or months (since v5 was released).\n\n## Compatibility\n\nButtercup's compatibility is defined as the following:\n\n * NodeJS version 12 and up\n * Current versions of the following browsers:\n   * Google Chrome\n   * Mozilla Firefox\n   * Safari\n * _React Native 0.60+_\n\n_NB: React Native support is not guaranteed under all circumstances as the platform's stability for low-level operations like cryptography is questionable. Use the [mobile app](https://github.com/buttercup/buttercup-mobile) as a guideline for implementation._\n\nBrowser support is strictly dependent on:\n\n * Popularity\n * The availability of required crypto libaries such as `SubtleCrypto`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbuttercup%2Fbuttercup-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbuttercup%2Fbuttercup-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbuttercup%2Fbuttercup-core/lists"}