Device account internals

Look under the hood at how a local signing identity founds an offline account and links other identities.

Device accounts, Jazz's local-first friendly auth method and how it does guests, separate a signing identity from the account that owns application data. A device account can be created offline; adding an external identity requires the core registry. Internally the identity's issuer is still urn:jazz:local-first.

Identity and account derivation

The client retains a 32-byte secret, represented as jazz-auth-v1:<43 unpadded base64url characters>. Native crypto derives an Ed25519 signing key using the jazz-auth-sign-v1 domain separator. Its public key determines the local identity's UUID subject in the jazz-auth-key-v1 namespace.

The identity is (urn:jazz:local-first, subject). Its founder account is a separate, application-scoped UUIDv5: the namespace is the normalized app UUID, and the name is jazz-account-founder-v1 followed by a zero byte and the subject. Therefore the same recovery secret restores the same identity and the same account within an application. A new secret creates a different identity and founder account.

The session prepares native crypto and the retained account selection when it starts. createDeviceAccount() (or initial: "device") creates the key and selects its account. A client waits for the key to be durably retained before using its credentials. Browser, React Native, and Expo adapters provide host storage (an AccountStore); the account-selection logic is shared. exportDeviceKey() returns the retained secret, and restoreDeviceAccount(key) selects the account it derives. Signing out clears the selection but keeps the secret, and records the sign-out, so initial: "device" creates no new key over it; reopenDeviceAccount() selects the retained secret whose account signed in most recently. With clearOnSignOut (rememberBackendUser: false), signing out drops the secret and tombstones its account.

Self-signed authentication

Device-account JWTs use Ed25519, iss: "urn:jazz:local-first", the derived identity subject, an application audience, and the embedded jazz_pub_key. The server verifies the signature, checks the audience and token lifetime, and confirms that the public key derives the claimed subject.

This proves control of the identity without an external JWKS provider. The deterministic founder rule lets core admit that identity's account without a competing registration choice. It does not let the caller choose an arbitrary account ID.

The core registry records the exact identity-to-account assignment. A signed-in user of the app's own auth gets an account when the app's backend vouches for them (refresh()), or joins an existing device account when the backend links them (linkDeviceAccount()).

Linking a signed-in user

The provider keeps its normal user ID. It does not rewrite it, accept a Jazz-specific signup proof, or mint custom linking claims.

The client calls linkDeviceAccount(). The session gracefully closes its current context with shutdown({ waitForSync: true }); if synchronization fails, it keeps that context. Once closed, the client asks the backend's backend-link/challenge route for a challenge. The backend runs authenticate and issues one that names that user, expires after two minutes, and carries a nonce; it is MACed with a key derived from the core's admin secret and the app ID, so any instance of this app's backend can check it and no other app's can. The client signs the challenge with its device key (signChallenge, a purpose-specific signature, not a JWT) and posts the challenge and proof to backend-link. The backend runs authenticate again, checks that the challenge is its own, fresh and for this user, and verifies the proof. It then founds the guest's account and links the user's identity (jazz:backend, user ID) to it with its admin secret, passing the challenge's nonce as the link's intent ID. The core records that intent and refuses a used nonce before anything else, so the same proof never links twice. A link is idempotent for the same guest and user: a fresh proof from a guest already linked to that user answers with the account (and, with guestKeyAfterLink: "revoke", retires the key if an earlier attempt didn't). The client opens a new context using the returned handle.

The guest's sync token is never a link proof. A leaked, unexpired token can't link the guest's account to another user, and a captured proof is good only for the user its challenge names, once.

The core accepts the link only if the user's identity is unassigned. An identity already assigned to another account cannot be moved or merged, including after revocation.

Existing rows retain their original structured authorship. Their account IDs stay unchanged, while new writes record the linked provider identity. Policies comparing $createdBy with session.user (the account) keep ownership stable; comparing $createdBy.identity with session.identity also distinguishes the acting identity.

If linking fails after the old context was closed, the session reopens the account still selected, stays ready with error set, and retry() repeats the link. See Device Accounts for the application flow.