{"id":15018574,"url":"https://github.com/eddyverbruggen/nativescript-secure-storage","last_synced_at":"2025-04-09T17:23:14.893Z","repository":{"id":13181150,"uuid":"73813271","full_name":"EddyVerbruggen/nativescript-secure-storage","owner":"EddyVerbruggen","description":":closed_lock_with_key: NativeScript plugin for secure local storage of fi. passwords","archived":false,"fork":false,"pushed_at":"2023-01-14T00:52:26.000Z","size":4165,"stargazers_count":111,"open_issues_count":27,"forks_count":26,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-02T10:45:18.864Z","etag":null,"topics":["hawk","keychain","nativescript","samkeychain"],"latest_commit_sha":null,"homepage":"","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/EddyVerbruggen.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}},"created_at":"2016-11-15T12:51:22.000Z","updated_at":"2024-07-08T20:12:13.000Z","dependencies_parsed_at":"2023-01-16T20:45:27.901Z","dependency_job_id":null,"html_url":"https://github.com/EddyVerbruggen/nativescript-secure-storage","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddyVerbruggen%2Fnativescript-secure-storage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddyVerbruggen%2Fnativescript-secure-storage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddyVerbruggen%2Fnativescript-secure-storage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EddyVerbruggen%2Fnativescript-secure-storage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EddyVerbruggen","download_url":"https://codeload.github.com/EddyVerbruggen/nativescript-secure-storage/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248075357,"owners_count":21043570,"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":["hawk","keychain","nativescript","samkeychain"],"created_at":"2024-09-24T19:52:08.070Z","updated_at":"2025-04-09T17:23:14.871Z","avatar_url":"https://github.com/EddyVerbruggen.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NativeScript Secure Storage plugin\n\n[![NPM version][npm-image]][npm-url]\n[![Twitter Follow][twitter-image]][twitter-url]\n\n[npm-image]:http://img.shields.io/npm/v/@nativescript/secure-storage.svg\n[npm-url]:https://npmjs.org/package/@nativescript/secure-storage\n[twitter-image]:https://img.shields.io/twitter/follow/eddyverbruggen.svg?style=social\u0026label=Follow%20me\n[twitter-url]:https://twitter.com/eddyverbruggen\n\n## Installation\nFrom the command prompt go to your app's root folder and execute:\n\n#### NativeScript 7 and later\n\n```\ntns plugin add @nativescript/secure-storage\n```\n\n#### Before NativeScript 7\n\n```\ntns plugin add nativescript-secure-storage\n```\n\n## Demo app\nWant to dive in quickly? Check out [the demo](demo)! Otherwise, continue reading.\n\nYou can run the demo app from the root of the project by typing `npm run demo.ios.device`.\n\n\u003cimg src=\"https://raw.githubusercontent.com/EddyVerbruggen/nativescript-secure-storage/master/screenshots/ios-demo.png?v=2\" width=\"375px\" height=\"500px\"/\u003e\n\n__PRO TIP:__ Want to store objects instead of strings? Use `JSON.stringify` with `set` and `JSON.parse` with `get`.\n\n## API\n\n### `set` | `setSync`\n\u003e \"In order to GET something you first need to SET it.\"\n\u003e\n\u003e -- _Eddy Verbruggen_\n\n##### JavaScript\n```js\n// require the plugin\nvar SecureStorage = require(\"nativescript-secure-storage\").SecureStorage;\n\n// instantiate the plugin\nvar secureStorage = new SecureStorage();\n\n// async\nsecureStorage.set({\n  key: \"foo\",\n  value: \"I was set at \" + new Date()\n}).then(\n  function(success) {\n    console.log(\"Successfully set a value? \" + success);\n  }\n);\n\n// sync\nvar success = secureStorage.setSync({\n  key: \"foo\",\n  value: \"I was set at \" + new Date()\n});\n```\n\n##### TypeScript\n```typescript\n// require the plugin\nimport { SecureStorage } from \"nativescript-secure-storage\";\n\n// instantiate the plugin\nlet secureStorage = new SecureStorage();\n\n// async\nsecureStorage.set({\n  key: \"foo\",\n  value: \"I was set at \" + new Date()\n}).then(success =\u003e console.log(\"Successfully set a value? \" + success));\n\n// sync\nconst success = secureStorage.setSync({\n  key: \"foo\",\n  value: \"I was set at \" + new Date()\n});\n```\n\n### `get` | `getSync`\nWill return `null` if not found.\n\n##### JavaScript\n```js\n// async\nsecureStorage.get({\n  key: \"foo\"\n}).then(\n  function(value) {\n    console.log(\"Got value: \" + value);\n  }\n);\n\n// sync\nvar value = secureStorage.getSync({\n  key: \"foo\"\n});\n```\n\n##### TypeScript\n```typescript\n// async\nsecureStorage.get({\n  key: \"foo\"\n}).then(value =\u003e console.log(\"Got value: \" + value));\n\n// sync\nconst value = secureStorage.getSync({\n  key: \"foo\"\n});\n```\n\n### `remove` | `removeSync`\n\n##### JavaScript\n```js\n// async\nsecureStorage.remove({\n  key: \"foo\"\n}).then(\n  function(success) {\n    console.log(\"Removed value? \" + success);\n  }\n);\n\n// sync\nvar success = secureStorage.removeSync({\n  key: \"foo\"\n});\n```\n\n##### TypeScript\n```typescript\n// async\nsecureStorage.remove({\n  key: \"foo\"\n}).then(success =\u003e console.log(\"Successfully removed a value? \" + success));\n\n// sync\nconst success = secureStorage.removeSync({\n  key: \"foo\"\n});\n```\n\n### `removeAll` | `removeAllSync`\n\n##### JavaScript\n```js\n// async\nsecureStorage.removeAll().then(\n  function(success) {\n    console.log(\"Removed value? \" + success);\n  }\n);\n\n// sync\nvar success = secureStorage.removeAllSync();\n```\n\n##### TypeScript\n```typescript\n// async\nsecureStorage.removeAll().then(success =\u003e console.log(\"Successfully removed a value? \" + success));\n\n// sync\nconst success = secureStorage.removeAllSync();\n```\n\n### `clearAllOnFirstRun` | `clearAllOnFirstRunSync`\nThese functions can be used if you want to clear data when your app is reinstalled.\n\nThis is only really useful **on iOS** because if you write something (through this plugin) to the Keychain, this data **won't** be removed when the app is uninstalled.\nSo the next time the same app is installed, it will find the data in the keychain.\n\nSo if you want to clear 'lingering' data from a previous install, make sure you run one of these\nmethods before using other methods this plugin provides.\n\n##### JavaScript\n```js\n// async\nsecureStorage.clearAllOnFirstRun().then(\n  function(success) {\n      console.log(success ? \"Successfully removed all data on the first run\" : \"Data not removed because this is not the first run\");\n  }\n);\n\n// sync\nvar success = secureStorage.clearAllOnFirstRunSync();\n```\n\n##### TypeScript\n```typescript\n// async\nsecureStorage.clearAllOnFirstRun().then(success =\u003e {\n    console.log(success ? \"Successfully removed all data on the first run\" : \"Data not removed because this is not the first run\");\n});\n\n// sync\nconst success = secureStorage.clearAllOnFirstRunSync();\n```\n\n### `isFirstRun` | `isFirstRunSync`\nAs a bonus, you can piggyback the 'first run' mechanism to do anything you want when the plugin detects\nthis is the first run (after an install or install-delete-reinstall).\n\n##### TypeScript\n```typescript\n// sync\nif (secureStorage.isFirstRunSync()) {\n  // do whatever you want\n}\n\n// async\nsecureStorage.isFirstRun().then(isFirst =\u003e {\n  // if isFirst is true, do whatever you like\n});\n```\n\n## Usage with Angular\n\nIn your view:\n\n```html\n\u003cButton text=\"set secure value\" (tap)=\"setSecureValue()\"\u003e\u003c/Button\u003e\n```\n\nIn your `@Component`:\n\n```typescript\nimport { SecureStorage } from \"nativescript-secure-storage\";\n\nexport class MyComponent {\n  secureStorage = new SecureStorage();\n\n  // a method that can be called from your view\n  setSecureValue() {\n    this.secureStorage.set({\n      key: 'myKey',\n      value: 'my value'\n    }).then(success =\u003e { console.log(success)});\n  }\n}\n```\n## iOS Security++\nBy default the plugin uses `kSecAttrAccessibleAlwaysThisDeviceOnly` access control to the keychain. This means that the keychain value can be accessed even if the device is locked. If you want to enhance security and you do not need background access, or if you want to allow the value to be backed up and migrated to another device, you can use any of keys defined [here](https://developer.apple.com/documentation/security/ksecattraccessiblealwaysthisdeviceonly?language=objc#see-also) and pass it when you create an instance of `SecureStorage`, for example\n```ts\ndeclare const kSecAttrAccessibleWhenUnlockedThisDeviceOnly; // This is needed in case you don't have tns-platform-declarations module installed. \nconst secureStorage = new SecureStorage(kSecAttrAccessibleWhenUnlockedThisDeviceOnly);\n```\n\n## iOS Simulator\n\nCurrently this plugin defaults to using `NSUserDefaults` on **iOS Simulators**. You can change this behaviour by providing `disableFallbackToUserDefaults` to the constructor of `SecureStorage`. This then uses the keychain instead of `NSUserDefaults` on simulators.\n\nIf you're running into issues similar to [issue_10](https://github.com/EddyVerbruggen/nativescript-secure-storage/issues/10), consider using the default behaviour again.\n\n## Credits\n* On __iOS__ we're leveraging the KeyChain using the [SAMKeychain](https://github.com/soffes/SAMKeychain) library (on the Simulator `NSUserDefaults`),\n* On __Android__ we're using [Hawk](https://github.com/orhanobut/hawk) library which internally uses [Facebook conceal](https://github.com/facebook/conceal).\n* Thanks, [Prabu Devarrajan](https://github.com/prabudevarrajan) for [adding the `deleteAll` function](https://github.com/EddyVerbruggen/nativescript-secure-storage/pull/11)!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feddyverbruggen%2Fnativescript-secure-storage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feddyverbruggen%2Fnativescript-secure-storage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feddyverbruggen%2Fnativescript-secure-storage/lists"}