Signing users in and out
Login and secrets is about one string: the token your API hands back, stored where the host can reach it. This page is about the other half, the one a phone makes awkward: the person holding it can change.
A token is replaced far more often than a user changes — every refresh does it — so the host cannot tell a refresh from a different person by the token alone. You tell it:
await call('auth.setToken', { token, account: user.id });account is your id for the user, opaque to Valence: a subject claim, a user id, a hash of the
email. Never a password, and nothing you would mind seeing in a log line. The host keeps it beside the
token in the Keystore, and auth.account() reads it back — it is the page’s own value, so reading it
back tells the page nothing it did not already know, and it is what makes “is the host still holding the
user I signed in?” answerable after a cold start.
What changes when the id changes
Section titled “What changes when the id changes”Nothing, as long as it is the same id. A refresh is a new token and no other effect.
When it is a different id — or when you sign out — the host does three things, in this order:
- It refuses if the outbox is not empty. The call throws
E_PENDINGand nothing changes: not the token, not the recorded id, not a row. - It clears every writable bucket: its rows, its
max_usncursor, the whole outbox and the host’s own freshness record, in one transaction. Read-only buckets are untouched — they are the same public rows for everybody, and they are what your app shows while nobody is signed in. Disposable REST cache overlays and the optional cookie jar go too: both can hold something that belongs to the account that just left. - Then it stores the new token, still holding the sync lease it took for the clear. That matters as much as the clear does: a sync starting in the gap would pull the previous account’s rows straight back, under the previous account’s token, because the host builds the header when it makes the request. The secure writes delete the old token, record the new id, clear the task snapshot and then store the new token. If a write fails or the process dies, the device keeps the original credentials or no bearer, never the new token under the old user’s id. Retry sign-in to recover.
The host serializes account-changing calls. Cancel an outstanding refresh when the user changes, or include the correct account id: a refresh without an id cannot say whose token it contains. Task restoration also checks the recorded identity, so an old OS snapshot cannot bring back the previous user’s route or draft. Redraw the page’s live account UI after a switch.
It also emits sync.changed for the cleared buckets, so a page that is
showing the previous user’s list redraws instead of waiting for a sync.
Why the refusal is the important part
Section titled “Why the refusal is the important part”The host attaches the stored token at the moment it makes the request, not at the moment the write was queued. So a sign-in that went through over a full outbox would push user A’s rows to your server under user B’s credentials, minutes later, from a background sync nobody was watching. That is a cross-account write, and your server has no way to see that it is one: the token is valid.
Hence the refusal, and hence the only way past it:
try { await call('auth.setToken', { token, account: nextUser.id });} catch (e) { if (e.code !== 'E_PENDING') throw e; // Offer the real choice. "Discard" deletes those writes unsent — they never reach the server. if (await askToDiscard(e.message)) { await call('auth.setToken', { token, account: nextUser.id, discardPending: true }); }}The better branch is usually the one above discardPending: call
sync.now() first, check that sync.status().pending is 0, and sign in
after. discardPending is for when the outbox cannot drain — the previous user is gone, the writes are
unsendable, and the person in front of you wants their own account.
While the switch is running, writes are refused
Section titled “While the switch is running, writes are refused”A switch has to clear the old account’s data and store the new token as one indivisible step, so for as
long as it runs the host refuses data.put with E_INTERNAL and a message saying nothing was written. A
write that arrived in that window belongs to neither account: queue it for the new one and it is the same
cross-account write by a slower route.
It is brief — one transaction, plus up to five seconds if a sync is in flight — but it is not zero, so do
not fire writes at the host while you are awaiting auth.setToken. Disable the form, await the call,
then re-enable it. If a write is refused, make it again afterwards; nothing was stored, so there is
nothing to undo.
This also holds when your app has no writable buckets left — say an update removed the last one.
There is nothing to delete, but rows queued under the config that admitted them are still there, so the
E_PENDING guard still applies and the outbox is still cleared when you pass discardPending.
Signing out
Section titled “Signing out”auth.setToken({ token: null }) clears the token, the recorded account and the same data, with the same
E_PENDING guard.
It does that only for an app that has recorded an account. If you have never passed account, sign-out
keeps the 0.3 behaviour exactly — the token goes, the rows stay — so upgrading your host does not hand
any app a data wipe it did not ask for. One exception, and it is not a row: the
cookie jar
is cleared by every sign-out, recorded account or not. Those cookies are credentials of the user who
just left, and no app signs a user out meaning to keep their session. A request that was already in
flight cannot put them back either: http.request takes no lease, so a response begun as one user can
arrive after the sign-out, and its Set-Cookie would otherwise refill the jar the sign-out just emptied
for the next user’s requests to send. The host stamps each request with the jar’s generation and drops
the cookies of a response whose generation no longer matches — and a request that straddles the change
sends no cookie out either, because its bearer token belongs to the account that is leaving. Your page
still gets the response — only its credentials are refused — so discard results fetched under the
previous account yourself. The first call that names an id when none is recorded adopts
it and clears nothing, which is what makes the upgrade safe: your current user is signed in on the
device right now, and wiping there would destroy the data of the person holding the phone.
So the adoption path for an app that already shipped is simply: start passing account on your next
sign-in, and the switch is armed from then on.
Gate it on auth.account
Section titled “Gate it on auth.account”account and discardPending are params, and a param has no since of its own — so
has('auth.setToken') cannot gate them, and app.info().bridge is the wrong number entirely (it is your
app’s own schema version; see the bridge guide). The
gate is the method that shipped with them:
import { call, has } from '#lib/valence/bridge.g';
const params = has('auth.account') ? { token, account: user.id } : { token };await call('auth.setToken', params);Send them to an older host and the generated decoders reject the unknown fields with E_PARAMS — the
sign-in fails outright. Skip the check and drop the params for everyone, and the hosts that do enforce
the switch never get told the account changed: no error, no switch, and the next user reads the previous
one’s rows. The gate is the difference.
Add them to your schema like any other growth, at the version they arrive in — the template’s is 13:
"auth.setToken": { "since": 2, "params": { "token": "string?", "account": "string?", "discardPending": "bool?" }, "returns": "void" },"auth.account": { "since": 13, "params": {}, "returns": "string?" }valence codegen refuses the params without auth.account beside them, for exactly the reason above.
What it does not do
Section titled “What it does not do”- It does not delete anything on your server. The wipe is local. User A’s rows stay where A can read them from their next device; no tombstone is pushed. A “delete my account” feature is your API’s.
- It does not touch read-only buckets, prefs or secure storage. Your own
secure.setkeys survive a switch — if one of them is user-scoped, clear it yourself whenauth.account()changes. A bucket you have since removed fromwritableis not cleared either: the host is only told about the current set. It logs those rows; move them or clear them yourself. - It is not a second user profile. There is one database and one signed-in user at a time. A device that must hold two accounts at once needs the account in your bucket keys, not here.