# Secure storage plugin

Source: https://saastostore.com/plugins/secure-storage

This plugin is a small key-value store encrypted by the phone, for a token or a secret your site needs from one launch to the next. It's a safer place than `localStorage`, whose content can be read from the app's files on a compromised device.

## How values are protected

| System | Where values live | After uninstalling |
| --- | --- | --- |
| Android | Encrypted with AES-256-GCM, with a key from the Android Keystore that never leaves the device | Erased, and never backed up |
| iOS | The Keychain, for this app only, on this device only, after first unlock | Kept: a reinstall finds the old values |

## Set it up

1. **Add the plugin** In your project's plugin library, add Secure storage, then launch a new build.
2. **Save and read your values** Keep your web code for browsers, and add these calls for the app.

## JavaScript API

```js
const vault = window.saastostore?.secureStorage;
await vault?.set("refresh_token", token);   // → { ok: true }
const saved = await vault?.get("refresh_token");
// → { value: "…" }, or { value: null } when the key is missing
await vault?.keys();                         // → { keys: ["refresh_token"] }
await vault?.remove("refresh_token");        // → { ok: true }
await vault?.clear();                        // e.g. at sign-out
await vault?.set("session", JSON.stringify({ id, exp })); // objects: JSON.stringify
await vault?.set("auth:token", undefined);
// → { ok: false, error: "invalid_argument" }   ":" in the key, value not a string
```

## Limits

- **Keys:** letters, digits, `.`, `_` and `-`, from 1 to 128 characters.
- **Values:** strings up to 64 KB. Nothing is converted: use `JSON.stringify` for objects.
- **One store per site:** like `localStorage`. `www.example.com` and `example.com` share one, `help.example.com` has its own.
- **Your page can read it:** values are protected on the phone, not against a script injected into your site.

> **Warning:** On iOS, the Keychain survives uninstalling the app. Call `clear()` at sign-out, and don't take an empty store for a first install, or the reverse.

## Prompt for AI builders

**Prompt for Lovable, Bolt or Base44**

```text
My website also runs inside a mobile app. Inside the app, window.saastostore?.secureStorage is an encrypted store. In a normal browser it doesn't exist, and nothing must change.

Inside the app, also save [VALUE TO PROTECT] with secureStorage.set(key, value). Keys use letters, digits, ".", "_" and "-" only, for example "auth.refresh_token". Values are strings: JSON.stringify objects, and never pass undefined. Read it with secureStorage.get(key), which returns { value }, and call secureStorage.clear() at sign-out.
```

Replace the value in [BRACKETS].

## Frequently asked questions

### Is it safer than localStorage?

Yes, on the phone: values are encrypted with keys held by the system. Against a script injected into your own site, no: your page can read both.

### Does it sync across devices?

No. Values stay on that device. On a new phone, the store starts empty.

### Do I still need my own server session?

Yes. This store keeps a value on the phone. It doesn't replace your authentication.