Access control

1. Which middleware sees what
2. Example
3. Projections

ShareDB has no built-in access control. Instead, you enforce it in middleware.

A client can read a document in two forms: as a snapshot, or as the ops that build it. These go through different middleware, so read access control must be enforced in both 'readSnapshots' and 'op' middleware.

The client chooses which form it asks for. Checking only 'readSnapshots' still lets a client read a document’s create data and its entire history by asking for its ops from version 0.

Which middleware sees what

Data sent to the client	Middleware
Snapshots: fetching or subscribing to a doc the client doesn’t have yet, bulk fetches and subscribes by id, query results (including docs added to a subscribed query’s results later), resubscribing to a query after reconnecting, fetchSnapshot() and fetchSnapshotByTimestamp()	'readSnapshots'
Ops: fetching or subscribing to a doc from a version, bulk fetches and subscribes from versions, resubscribing to a query after reconnecting, ops on subscribed docs and query results as they happen, and ops the client missed, sent back after it submits	'op'
Queries – this runs before the query, and doesn’t see its results	'query'
A query’s extra, such as a count or aggregation from your database adapter – 'reply' sees it in the first reply, but not in a subscribed query’s later updates, so reject queries whose extra the client shouldn’t see	'query'
Presence	See presence access control
Writes	See op submission

Example

function canRead(agent, collection, id) {
  // Your own rule, e.g. checking against agent.custom.userId
}

function canQuery(agent, collection, query) {
  // Your own rule, e.g. only allowing queries scoped to agent.custom.userId
}

backend.use('readSnapshots', (context, next) => {
  for (const snapshot of context.snapshots) {
    if (!canRead(context.agent, context.collection, snapshot.id)) {
      context.rejectSnapshotRead(snapshot, new Error('Forbidden'))
    }
  }
  next()
})

backend.use('op', (context, next) => {
  if (!canRead(context.agent, context.collection, context.id)) {
    return next(new Error('Forbidden'))
  }
  next()
})

backend.use('query', (context, next) => {
  if (!canQuery(context.agent, context.collection, context.query)) {
    return next(new Error('Forbidden'))
  }
  next()
})

In a bulk fetch or subscribe, context.rejectSnapshotRead() rejects just that snapshot, and the rest of the request still succeeds. Queries can’t partially succeed: if any of a query’s snapshots is rejected, the whole query fails, and a subscribed query drops that update. Use 'query' middleware to keep queries to documents the client can read – for example, by narrowing context.query, whose shape depends on your database adapter – and treat 'readSnapshots' as the backstop for the documents a query returns.

Narrowing a query only limits its results. A client resubscribing to a query after reconnecting names the documents it already has, and reading those is checked only by 'readSnapshots' and 'op'.

There is no per-op equivalent of rejectSnapshotRead(): rejecting an op fails the whole fetch or subscribe that read it, including a query resubscribe. So if a client loses access to one of a subscribed query’s documents while it’s offline, the query errors when it reconnects. A live op that 'op' rejects as it arrives over pub/sub is logged and dropped instead: the client’s doc doesn’t error, but stops updating until its next fetch or resubscribe, which is then rejected.

'op' runs once for every op read, so a client catching up from version 0 triggers it for every op in the document’s history. Keep the check cheap: for example, by caching permissions on agent.custom.

Projections

For a projection, context.collection in 'readSnapshots' and 'op' is the projection’s target collection, and the snapshot or op has already been projected.

A query on a projection can still filter or sort on fields outside it, so which documents it returns can reveal those fields, even though 'readSnapshots' only sees the projected results. If you rely on a projection to hide fields, restrict which fields a query may filter or sort on in 'query' middleware.