Skip to content
Valence is in beta. The bundle format and update protocol are meant to stay stable; the CLI, the generated code and the two runtime packages’ APIs may still change. What beta means

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.

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:

  1. It refuses if the outbox is not empty. The call throws E_PENDING and nothing changes: not the token, not the recorded id, not a row.
  2. It clears every writable bucket: its rows, its max_usn cursor, 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.
  3. 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.

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.

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.

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.

  • 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.set keys survive a switch — if one of them is user-scoped, clear it yourself when auth.account() changes. A bucket you have since removed from writable is 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.