Duolith docs

0052. On the web, secure storage encrypts with a non-extractable key, and sign-in redirects with PKCE

  • Status: Proposed
  • Date: 2026-11-14
  • Decided by: integrator (internal only)
  • Planning item: WP11 (platform effects)

Context

Secure storage and sign-in must work on the web today, where there is no keychain and no system sign-in sheet, without pretending to be as strong as iOS and Android.

Decision

Secure storage encrypts each value with AES-GCM (a fresh 96-bit IV, the value's name as additional data) under one 256-bit key generated by WebCrypto as non-extractable; the key and the encrypted values are in one IndexedDB object store. Without WebCrypto or IndexedDB (an insecure page) it fails with E0222 instead of storing in the clear; a value that cannot be decrypted fails with E0227. The key sits in the same database as the values, so this protects against casual viewing, not against an offline copy of the browser profile, nor against script running on the site; packages/effects/README.md says so in full. Tabs share the database without losing data: the key is added only when absent, inside one transaction, and read again for every value, and a value is written only while the key that sealed it is still the stored one.

Sign-in with Apple and Google uses the authorization code flow with PKCE (S256) as a full-page redirect. The verifier and a random state are kept in sessionStorage, so only the tab that started a sign-in can finish it; a mismatched state is E0225, and an address with no answer is E0224. Each sign-in sends an OpenID Connect nonce, which the backend gets to check against the ID token. The app's backend swaps the code and verifier for tokens. Apple's form-post response mode (needed when asking for name or email) needs a server endpoint and is left to the backend.

The session's public part (the user) is kept in key-value storage and the credentials in secure storage, so who is signed in is known synchronously at start, for guards. At start, and whenever accessToken() is asked, missing or unreadable credentials end the session. An expired token is refreshed through the backend's optional refresh, or ends the session.

A magic link is bound to the device that asked for it: that device keeps a random nonce and sends only its SHA-256 hash with the email, and verifyMagicLink(token, nonce) signs in only when they match. Opened elsewhere, the link signs no one in until the user confirms, so a link someone else asked for cannot sign the user in to their account unnoticed (login CSRF).

Alternatives considered

OptionWhy not
Values in localStorage, unencryptedReadable by anything that reads the profile's files or dumps storage
A key derived from a user passphraseA prompt the native targets do not have; one way to do each thing
Popup windows for OAuthBlocked by default on many browsers, and awkward on phones
Implicit flow (tokens in the URL fragment)Deprecated by OAuth 2.1; tokens end up in history
Session read from secure storage at startAsynchronous, so guards would see "signed out" for a moment and redirect

Consequences

The user's id, name and email sit unencrypted in localStorage (as they would be on screen); tokens do not. Clearing site data signs the user out on the next read. The mock backend in @duolith/effects checks the PKCE pair for real, so examples exercise the same path as production.