Protected Store

Keep device secrets behind biometric or passcode authentication

One.ProtectedStore keeps a separate protected namespace for secrets that require device authentication to read or change. Unlike One.SecureStore, every item carries an access control policy fixed at creation. All calls are async, so a system authentication prompt never blocks the JavaScript thread.

On iOS items live in the Keychain behind SecAccessControl, unlocking through LAContext. On Android each item gets its own Keystore key with encrypted records on API 30 and later, unlocking per operation through BiometricPrompt. Web and older Android never read or write an unprotected substitute; they stay unavailable.

Usage

import { One } from 'one'

async function saveRecoveryKey(secret: string, nextSecret: string) {
  await One.ProtectedStore.createItem('recovery-key', secret, 'biometryCurrentSet')
  const value = await One.ProtectedStore.getItem(
    'recovery-key',
    'Unlock your recovery key',
    'biometryCurrentSet'
  )
  await One.ProtectedStore.updateItem(
    'recovery-key',
    nextSecret,
    'Update your recovery key',
    'biometryCurrentSet'
  )
  await One.ProtectedStore.deleteItem('recovery-key', 'Remove your recovery key', 'biometryCurrentSet')
  return value
}

Every read and mutation takes the reason the system shows and the policy fixed at creation. Creation takes no reason on Android, where it prompts nothing.

How it works

Set native.app.ios.faceIdUsageDescription before prebuilding, including for Touch ID apps. One’s Android library manifest declares the normal install-time biometric permission, which the manifest merger adds to the app; an app that strips it rejects every call.

userPresence accepts biometrics or the device passcode. biometryCurrentSet requires the currently enrolled biometrics and invalidates the item when that enrollment changes. Both keep the item on this device and available only while unlocked. Pass the same policy to later reads and mutations; a mismatch rejects. updateItem changes the value while keeping the policy. createItem rejects when the key exists; delete first to recreate under another policy.

getItem returns null for a missing item. An item invalidated by an enrollment change cannot be read, but deleteItem removes it so the key can be reused. updateItem rejects for a missing key while deleteItem succeeds for one. A cancelled prompt rejects as cancelled; authentication failures reject as auth errors.

On Android every read or update authenticates one fresh private-key operation, and deleting an existing item needs fresh authentication too. Calls made while locked reject without prompting or changing the item. A missing result applies only when both the encrypted record and its Keystore alias are absent. Values and temporary encryption keys are never stored as plaintext.

API reference

The policy is userPresence or biometryCurrentSet.

Platform differences

Limits and gotchas

• The policy never changes. It fixes at creation for the item’s lifetime. Delete and recreate to move a secret to another policy.
• Enrollment changes kill strict items. biometryCurrentSet invalidates on re-enrollment. Catch the read failure, delete, and re-enroll the secret.
• Authenticate from user actions. Prompts interrupt the screen and Android needs the device unlocked. Never read in the background.
• Creation prompts on iOS only. Android creation authenticates nothing; reads, updates, and deletes each authenticate fresh.
• No silent fallback exists. Unavailable platforms reject or read null rather than storing plaintext. Design for that.

Examples

import { One } from 'one'

const POLICY = 'biometryCurrentSet' as const

async function readRecoveryKey() {
  const value = await One.ProtectedStore.getItem(
    'recovery-key',
    'Unlock your recovery key',
    POLICY
  )
  if (value === null) {
    await One.ProtectedStore.deleteItem('recovery-key', 'Clear stale key', POLICY)
    return null
  }
  return value
}

A null read after an enrollment change means an invalidated item; the explicit delete frees the key for a fresh secret on the next setup.

import { One } from 'one'

async function rotateToken(next: string) {
  try {
    await One.ProtectedStore.updateItem(
      'api-token',
      next,
      'Rotate your API token',
      'userPresence'
    )
  } catch (error) {
    if ((error as { code?: string }).code === 'E_PROTECTED_STORE_NOT_FOUND') {
      await One.ProtectedStore.createItem('api-token', next, 'userPresence')
      return
    }
    throw error
  }
}

Update keeps the policy while swapping the value. The not-found branch covers first-run, creating under the same policy the update would have kept.