Guides / Secure storage and sessions

Secure storage and sessions

Keep notes in files or SQLite. Store credentials with oro:secure-storage, then restore the session on launch.

1) Store a session token after sign-in#

import * as secureStorage from 'oro:secure-storage'

export async function storeSession(session) {
  await secureStorage.setItem('refresh-token', session.refreshToken)
  await secureStorage.setItem('api-base-url', session.apiBaseUrl)
}

By default the runtime scopes storage to the current app origin, which is usually what you want.

2) Restore the session on startup#

import * as secureStorage from 'oro:secure-storage'

export async function loadSession() {
  const refreshToken = await secureStorage.getItem('refresh-token')
  const apiBaseUrl = await secureStorage.getItem('api-base-url')

  if (!refreshToken || !apiBaseUrl) return null
  return { refreshToken, apiBaseUrl }
}

This lets the app recover cleanly after restart without leaking secrets into source-controlled config.

3) Use explicit scopes when you need separation#

If the app talks to multiple environments, isolate them:

await secureStorage.setItem('refresh-token', token, {
  scope: 'https://staging.example.com',
})

That prevents staging and production credentials from clobbering each other.

4) Enumerate and clear keys during sign-out#

import * as secureStorage from 'oro:secure-storage'

const keys = await secureStorage.keys()
console.log(keys)

await secureStorage.removeItem('refresh-token')
await secureStorage.removeItem('api-base-url')

If your app stores a full session namespace, clear() is also available.

5) Keep binary secrets binary#

If you are storing keys or opaque encrypted values, do not base64 them unless you need portability:

const bytes = crypto.getRandomValues(new Uint8Array(32))
await secureStorage.setItem('device-key', bytes)

const restored = await secureStorage.getItem('device-key', {
  encoding: 'buffer',
})

That avoids unnecessary conversions and accidental text encoding bugs.

Considerations#

Runtime 0.2 adds Android secureStorage.getStatus() to inspect existing Keystore metadata without creating a key or decrypting saved values. requiresRecovery means ciphertext exists without its key; preserve it and use explicit recovery. A present key does not prove all records are readable, and other platforms do not implement this Android metadata probe.

For per-operation protected encryption or signing, use oro:authentication; for an explicit password-provider chooser, use oro:credentials. Stored secrets, local cryptographic authentication, and server authorization are separate boundaries. See native platform services and historical migration before changing existing protected stores.

  • Do not put secrets in oro.toml, .ororc, or bundled JSON files.
  • Prefer one storage key per concern (refresh-token, device-key, signing-state) instead of one opaque bag of JSON.
  • Pair secure storage with ordinary application state. The secret unlocks the session; SQLite and files hold the user-visible data.

Next#

Source repository · Edit this page · View Markdown

Quick links

Type to search across the site. Use the up and down arrow keys to choose a result, Enter to open it, and Escape to close.