{"id":13447671,"url":"https://github.com/WebReflection/safer-pass","last_synced_at":"2025-03-22T01:31:12.612Z","repository":{"id":65993262,"uuid":"186884741","full_name":"WebReflection/safer-pass","owner":"WebReflection","description":"A safer and easy way to protect with password text or files.","archived":false,"fork":false,"pushed_at":"2019-06-03T08:27:02.000Z","size":55,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-11T01:52:07.408Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WebReflection.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}},"created_at":"2019-05-15T18:47:58.000Z","updated_at":"2019-10-29T12:31:44.000Z","dependencies_parsed_at":"2023-07-11T14:34:22.301Z","dependency_job_id":null,"html_url":"https://github.com/WebReflection/safer-pass","commit_stats":{"total_commits":20,"total_committers":1,"mean_commits":20.0,"dds":0.0,"last_synced_commit":"2fcd7a7e5831266279899ed4f62040d40d3a81d0"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebReflection%2Fsafer-pass","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebReflection%2Fsafer-pass/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebReflection%2Fsafer-pass/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebReflection%2Fsafer-pass/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WebReflection","download_url":"https://codeload.github.com/WebReflection/safer-pass/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244893427,"owners_count":20527587,"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":[],"created_at":"2024-07-31T05:01:23.986Z","updated_at":"2025-03-22T01:31:12.325Z","avatar_url":"https://github.com/WebReflection.png","language":"JavaScript","readme":"# safer-pass\n\n\u003csup\u003e**Social Media Photo by [freestocks.org](https://unsplash.com/@freestocks) on [Unsplash](https://unsplash.com/)**\u003c/sup\u003e\n\n[![Build Status](https://travis-ci.com/WebReflection/safer-pass.svg?branch=master)](https://travis-ci.com/WebReflection/safer-pass) [![Coverage Status](https://coveralls.io/repos/github/WebReflection/safer-pass/badge.svg?branch=master)](https://coveralls.io/github/WebReflection/safer-promise?branch=master) ![WebReflection status](https://offline.report/status/webreflection.svg)\n\nA safer and easy way to protect with password text or files.\n\n#### v1 breaking change\n\nThe `Pass` constructor signature is now `Pass(password[, salt[, iv]])`.\n\n\n### Background\n\nCryptography isn't easy, and the current [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) is not making it any easier for Web developers to simply protect some text, file, or image, with a user defined password.\n\nNot only the [Web Crypto API is easy to crack](https://github.com/WebReflection/safer-crypto#safer-crypto), for any malicious 3rd parts script running in the wild, its usage is also fairly complicated, 'cause complicated is indeed the subject as a whole.\n\nThis module uses all [techniques recognized as able to make JS safer](https://github.com/domenic/get-originals), and it tries to simplify the topic without necessarily making it any less safe than it should.\n\n\n## The Password Protection's ABC\n\nThere are 3 terms, or variables, to keep in mind:\n\n  * the **user password**\n  * the **salt**\n  * the **initialization vector** (IV)\n\nThe least important thing is usually, and unfortunately, the _user password_, keep reading to know more.\n\n\n### The user password\n\nBoth 'cause humans aren't too good at remembering long sentences, and mostly because every service online asks you to comply with absurd rules, we have our fingers print and our finances authenticated through a 4 to 6 digits pin. and yet if we chose passwords by ourselves, with our rules, they believe we're doomed.\n\nSee [xkcd comic 936](https://xkcd.com/936/) to know more.\n\nAnyway, the first thing to remember is that our favorite password is usually not good enough.\n\n\n### The salt\n\nA _salt_ is usually `\"a very long and unique string\"` that a server, or a computer, but not usually a browser, is very good at keeping secret.\n\nA _salt_ is usually mandatory to avoid storing passwords in clear, but it's also not something you want to pass around.\n\nDue to its controversial nature, this module provides a way to define a specific salt, but it's not in the ABC nature of this paragraph that you'll learn more about it.\n\nPlease [do investigate mote about salts](https://en.wikipedia.org/wiki/Salt_(cryptography)) to improve security.\n\n\n### The (IV) Initialization Vector\n\nThis is the most important variable of them all: you either know it, or you'll hardly crack the encrypted data.\n\nThe _IV_ is a random generated _salt_ like variable, that is used to add some sort of unpredictable encryption, and it's mandatory to be able, password or not, to decrypt such data.\n\nThis means that an instance of `Pass` that doesn't use a shared `IV`, will be the only one able to encrypt and decrypt its own data.\n\n```js\nimport {IV, Pass} from 'safer-pass';\n\nconst user1 = new Pass(password);\nconst user2 = new Pass(password);\n\n// user1 can encrypt and decrypt data\nuser1\n  .encrypt(data)\n  .then(buffer =\u003e user1.decrypt(data))\n  .then(console.log);\n\n// but user2 cannot decrypt user1 data\nuser1\n  .encrypt(data)\n  .then(buffer =\u003e user2.decrypt(data))\n  .catch(error =\u003e {\n    console.error('Ooooooops, the IV is not the same!');\n  });\n```\n\n\n## How to encrypt and decrypt at distance\n\nThe 2 things that users need to know, one by heart, and one by their machine, is the password, and the IV.\n\n```js\nimport {IV, Pass} from 'safer-pass';\n\nconst SALT = 'some-very-long-and-unique-secret';\n\nconst sharedIV = new IV;\nconst user1 = new Pass(password, SALT, sharedIV);\nconst user2 = new Pass(password, SALT, sharedIV);\n\n// user1 can encrypt and user2 can decrypt data\nuser1\n  .encrypt(data)\n  .then(buffer =\u003e user2.decrypt(data))\n  .then(console.log);\n\n```\n\n\n## How to transfer encrypted data\n\nAssuming both users know the same `password` and optionally, but recommended, the same `salt`, the module offer an instance `serialize` and a static `unserialize` method.\n\n```js\n// from user1 side\nimport {Pass} from 'safer-pass';\n\nconst SALT = 'some-very-long-and-unique-secret';\n\nconst user1 = new Pass(\n  password,\n  SALT\n);\nuser1.serialize('secret info').then(transfer);\n\n// from user2 side\nimport {Pass} from 'safer-pass';\nreceive()\n  .then(\n    data =\u003e Pass.unserialize(\n      data,\n      password,\n      SALT\n    )\n  )\n  .then(console.log);\n```\n\n# API\n\nThere are two classes provided with this module, the `IV` one, and the `Pass` one.\n\n## IV\n\n```js\nclass IV extends Uint8Array {\n\n  static from(value) {\n    // return an IV from a buffer or a string\n  }\n\n  constructor(length = 16) {\n    // creates an IV with length 16 by default\n  }\n\n  toString() {\n    // return a string representation of the IV\n  }\n}\n```\n\n\n## Pass\n\n```js\nclass Pass {\n\n  static unserialize(serializeed, password, salt) {\n    // return a promise that resolves as decrypted data\n  }\n\n  constructor(\n    password,     // either a string or a buffer\n    salt = '...', // an optional salt to use\n    iv = new IV   // am optional random buffer to use\n  ) {\n    // creates a frozen instance of Pass\n  }\n\n  decrypt(input, returnString = false) {\n    // return a promise with decrypted data\n    // either as buffer, or string\n  }\n\n  encrypt(input, returnString = false) {\n    // return a promise with encrypted data\n    // either as buffer, or string\n  }\n\n  serialize(input) {\n    // return a promise with an object\n    // usable to transfer data, being saved in a db\n    // or being posted via JSON.stringify\n  }\n\n}\n```\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FWebReflection%2Fsafer-pass","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FWebReflection%2Fsafer-pass","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FWebReflection%2Fsafer-pass/lists"}