Auth

LiveStore doesn’t include built-in authentication or authorization support, but you can implement it in your app’s logic.

Pass an auth payload to the sync backend

Use the syncPayload store option to send a custom payload to your sync backend.

Example

The following example sends the authenticated user’s JWT to the server.

live-store-provider.tsx

export const AuthenticatedProvider = () => (
  <LiveStoreProvider
    schema={schema}
    storeId={storeId}
    adapter={adapter}
    batchUpdates={batchUpdates}
    syncPayload={{
      authToken: user.jwt, // Using a JWT
    }}
  >
    {/* ... */}
    {children}
)

On the sync server, validate the token and allow or reject the sync based on the result. See the following example:

pass-auth-payload.ts

import { makeDurableObject, makeWorker } from '@livestore/sync-cf/cf-worker'
import * as jose from 'jose'

const JWT_SECRET = 'a-string-secret-at-least-256-bits-long'

export class SyncBackendDO extends makeDurableObject({
  onPush: async (message) => {
    console.log('onPush', message.batch)
  },
  onPull: async (message) => {
    console.log('onPull', message)
  },
}) {}

export default makeWorker({
  syncBackendBinding: 'SYNC_BACKEND_DO',
  validatePayload: async (payload: any, context) => {
    const { storeId } = context
    const { authToken } = payload

    if (!authToken) {
      throw new Error('No auth token provided')
    }

    const user = await getUserFromToken(authToken)

    if (!user) {
      throw new Error('Invalid auth token')
    } else {
      // User is authenticated!
      console.log('Sync backend payload', JSON.stringify(user, null, 2))
    }

    // Check if token is expired
    if (payload.exp && payload.exp < Date.now() / 1000) {
      throw new Error('Token expired')
    }

    await checkUserAccess(user, storeId)
  },
  enableCORS: true,
})

async function getUserFromToken(token: string): Promise<jose.JWTPayload | undefined> {
  try {
    const { payload } = await jose.jwtVerify(token, new TextEncoder().encode(JWT_SECRET))
    return payload
  } catch (error) {
    console.log('⚠️ Error verifying token', error)
  }
}

async function checkUserAccess(payload: jose.JWTPayload, storeId: string): Promise<void> {
  // Check if user is authorized to access the store
  console.log('Checking access for store', storeId, 'with payload', payload)
}

The above example uses jose, a popular JavaScript module that supports JWTs. It works across various runtimes, including Node.js, Cloudflare Workers, Deno, Bun, and others.

The validatePayload function receives the authToken, checks if the payload exists, and verifies that it’s valid and hasn’t expired. If all checks pass, sync continues as normal. If any check fails, the server rejects the sync.

The client app still works as expected, but saves data locally. If the user re-authenticates or refreshes the token later, LiveStore syncs any local changes made while the user was unauthenticated.

Re-validate payload inside the Durable Object

When you rely on syncPayload, treat it as untrusted input. Decode the token inside validatePayload to gate the connection, and then repeat the same verification inside the Durable Object before trusting per-push metadata.

keep-payload-canonical.ts verify-jwt.ts

type SyncPayload = { authToken?: string; userId?: string }

type AuthorizedSession = {
  authToken: string
  userId: string
}
const ensureAuthorized = (payload: unknown): AuthorizedSession => {
  if (payload === undefined || payload === null || typeof payload !== 'object') {
    throw new Error('Missing auth payload')
  }

  const { authToken, userId } = payload as SyncPayload
  if (!authToken) {
    throw new Error('Missing auth token')
  }

  const claims = verifyJwt(authToken)
  if (!claims.sub) {
    throw new Error('Token missing subject claim')
  }

  if (userId !== undefined && userId !== claims.sub) {
    throw new Error('Payload userId mismatch')
  }

  return { authToken, userId: claims.sub }
}

export default makeWorker({
  syncBackendBinding: 'SYNC_BACKEND_DO',
  validatePayload: (payload) => {
    ensureAuthorized(payload)
  },
})

export class SyncBackendDO extends makeDurableObject({
  onPush: async (message: SyncMessage.PushRequest, { payload }) => {
    const { userId } = ensureAuthorized(payload)
    await ensureTenantAccess(userId, message.batch)
  },
}) {}

const ensureTenantAccess = async (_userId: string, _batch: SyncMessage.PushRequest['batch']) => {
  // Replace with your application-specific access checks.
}


export type Claims = {
  sub?: string
}

type SyncPayload = { authToken?: string; userId?: string }

type AuthorizedSession = {
  authToken: string
  userId: string
}

const ensureAuthorized = (payload: unknown): AuthorizedSession => {
  if (payload === undefined || payload === null || typeof payload !== 'object') {
    throw new Error('Missing auth payload')
  }

  const { authToken, userId } = payload as SyncPayload

• validatePayload runs once per connection and rejects mismatched tokens before LiveStore upgrades to WebSocket.
• onPush (and onPull, if you need it) must repeat the verification because the payload forwarded to the Durable Object is the original client input.
• The HTTP transport does not forward payloads today; embed the necessary authorization context directly in the events or move those clients to WebSocket/DO-RPC if you must rely on shared payload metadata.

You can extend ensureAuthorized to project additional claims, memoise verification per authToken, or enforce application-specific policies without changing LiveStore internals.

Client Identity vs User Identity

LiveStore’s clientId identifies a client instance, while user identity is an application-level concern that must be modeled through your application’s events and logic.

Key Points

• clientId: Automatically managed by LiveStore, identifies a client instance
• User identity: Managed by your application through events and syncPayload

Using syncPayload for Authentication

The syncPayload is primarily intended for authentication purposes:

live-store-provider.tsx

export const AuthenticatedProvider = () => (
  <LiveStoreProvider
    schema={schema}
    storeId={storeId}
    adapter={adapter}
    batchUpdates={batchUpdates}
    syncPayload={{
      authToken: user.jwt, // Using a JWT
    }}
  >
    {/* ... */}
    {children}
)

User identification and semantic data (like user IDs) should typically be handled through your event payloads and application state rather than relying solely on the sync payload.