Permissions

DeepSpace enforces permissions in the Durable Object - the server checks every read and write before it broadcasts to clients. Permissions are declared per-collection in the schema.

Roles#

Every user has a role on each app's RecordRoom. The built-in roles are:

New authenticated users get member by default. Override that with defaultRole on the users schema. The only in-SDK way to promote a user is useUsers().setRole(userId, 'admin'), which the server rejects unless the caller is already an admin. The app owner is pinned to admin at connect time, so you don't promote them manually.

Unauthenticated callers use the '*' wildcard key in the permissions block - there is no anonymous role identifier.

The permissions block#

Every collection schema has a permissions object mapping role to operations:

permissions: {
  '*':    { read: 'published', create: false, update: false, delete: false },
  viewer: { read: 'published', create: false, update: false, delete: false },
  member: { read: true,         create: true,  update: 'own', delete: 'own' },
  admin:  { read: true,         create: true,  update: true,  delete: true },
}

read, update, and delete each accept a PermissionLevel - the union of boolean | 'own' | 'unclaimed-or-own' | 'collaborator' | 'team' | 'access' | 'published' | 'shared'. create is the exception: it accepts a boolean only - you either let a role create rows or you don't.

The levels you'll reach for most often:

Less common:

• 'unclaimed-or-own' - requires ownerField; passes when that field is empty, or when the caller is the owner. Without ownerField set, behaves identically to 'own'.
• 'collaborator' - owner OR in collaboratorsField (owners always pass)
• 'access' - equivalent to 'team'; prefer 'team' for clarity

Import the type from deepspace/worker to typecheck against the full union:

import type { PermissionLevel } from 'deepspace/worker'

visibilityField and collaboratorsField#

When you use 'published' or 'shared', you tell the SDK which column to check:

{
  name: 'posts',
  columns: [
    { name: 'title',  storage: 'text', interpretation: 'plain' },
    { name: 'status', storage: 'text', interpretation: { kind: 'select', options: ['draft', 'published'] } },
    { name: 'collaborators', storage: 'text', interpretation: { kind: 'json' } },
  ],
  visibilityField:    { field: 'status', value: 'published' },
  collaboratorsField: 'collaborators',
  permissions: {
    member: { read: 'shared', create: true, update: 'own', delete: 'own' },
  },
}

• visibilityField declares which column gates the 'published' and 'shared' rules. Use the string form ('status') to match when data.status === 'public', or the object form ({ field, value }) for any other sentinel value.
• collaboratorsField declares which column holds the JSON array of collaborator userIds checked by 'shared', 'collaborator', and 'team'.
• teamField (used by 'team' / 'access') declares which column holds the team ID. Membership is resolved against a team_members collection in the same scope, which must declare teamId, userId, and status columns - a row counts as a member when status is 'active' or null. Without a team_members collection registered, 'team' checks always fail. The built-in WORKSPACE_SCHEMAS ships one.

ownerField#

By default, 'own' checks against record.createdBy (set automatically when the record was created). To tie ownership to a different field (for example, an assignedTo user instead of the creator), set ownerField:

{
  name: 'todos',
  columns: [...],
  ownerField: 'assignedTo',
  permissions: {
    member: { read: true, update: 'own', delete: 'own' },
  },
}

Now 'own' resolves against record.data.assignedTo.

uniqueOn - one-per-user rules#

Permissions decide who may write; uniqueOn decides how many times. It declares a composite uniqueness constraint over a set of columns, and the Durable Object checks it on every create and update before the row is written - so "one vote per user per poll", "one RSVP per event", "one membership row per channel" hold against a forged or replayed client write, not just against a well-behaved UI. Pair it with userBound: true on the user column and the guarantee is complete: the client cannot choose whose row it is, and it cannot create a second one.

{
  name: 'votes',
  columns: [
    { name: 'pollId', storage: 'text', interpretation: 'plain', required: true },
    { name: 'userId', storage: 'text', interpretation: 'plain', userBound: true, immutable: true },
    { name: 'choice', storage: 'text', interpretation: 'plain', required: true },
  ],
  uniqueOn: ['pollId', 'userId'],
  ownerField: 'userId',
  permissions: {
    member: { read: true, create: true, update: 'own', delete: 'own' },
  },
}

A violation on a create or update is a refusal on the write's ack, not a thrown exception: the ack carries success: false with Duplicate: a record with pollId=…, userId=… already exists in votes. Handle it as the "already voted" branch. Updating choice succeeds because the unique tuple stays the same; an update that moves a row onto another row's tuple is refused.

Worked examples#

A blog with public posts and member-only drafts#

permissions: {
  '*':    { read: 'published', create: false, update: false, delete: false },
  member: { read: true,        create: true,  update: 'own', delete: 'own' },
  admin:  { read: true,        create: true,  update: true,  delete: true },
}

Visitors see only published posts. Members see their own drafts. Admins see everything. (The collection also needs visibilityField set - see above - for 'published' to resolve.)

A shared workspace with collaborators#

permissions: {
  member: { read: 'shared', create: true, update: 'shared', delete: 'own' },
  admin:  { read: true, create: true, update: true, delete: true },
}

Members read and edit anything they own or are listed as a collaborator on. Only the original owner can delete (or an admin).

A private user-scoped collection#

permissions: {
  member: { read: 'own', create: true, update: 'own', delete: 'own' },
}

Each user sees only their own records. Useful for things like personal preferences, drafts, or AI chat history.

Server-side enforcement#

The rules are enforced inside the Durable Object's canRead() / canWrite() checks. Three things follow from this:

1. Permissions are checked before data ships over the wire. A user without read access never receives the records - they're filtered out at the DO before the WebSocket broadcast.
2. Client-side filtering is not enough. Don't rely on the UI to hide records the user shouldn't see. A determined attacker reading WebSocket frames sees exactly what the DO sent.
3. Bypassing RBAC requires a server action. See Server actions - they call privileged worker code with the X-App-Action header, which bypasses RBAC for orchestration that the user themselves couldn't perform.

The users directory#

useUsers() is not a raw query over the users collection - it has its own privacy contract, enforced in the DO:

1. Anonymous sockets receive no directory. A public room must not turn the users table into a public directory, so unauthenticated connections get an empty list.
2. Non-admins get the public-identity projection of every registered user. Each row is cut down to id, name, imageUrl, role, and lastSeenAt - the fields collaborators need to name each other and to see who is around - regardless of the row-level read rule ('own', 'team', ...). The row rule still governs full-row reads: useQuery('users') and the admin directory. Admins get the full row through their read policy - which is why useUserLookup().getEmail resolves only for admins. usePresence() reads lastSeenAt straight off this roster, so online/offline works for every role, not only for admins.
3. Two opt-outs live on the users schema. A role whose read is false (or absent) receives an empty directory. roster: 'read-policy' scopes the directory to the rows the caller's read rule grants (still projected to public identity) - for apps that partition users by tenant or team and must not show names across the partition. Note that with it, every surface that names a peer through useUsers() (chat authors, assignees, presence) shows Unknown for users outside the caller's rows.

The scaffold ships member: { read: 'own' } on the users schema, so a regular member's useQuery('users') is self-only while their useUsers() directory names everyone. Set roster: 'read-policy' deliberately when the product needs the directory partitioned too.

useUserLookup().getName(userId) returns null for a peer the caller's roster does not contain - it resolves against the roster, and there is no server round-trip for a miss. The "Unknown" you see rendered next to an author or assignee is the app's own fallback for that null, not a value the SDK produced; choose whatever label fits your product.

The directory from the server side#

Two other paths read the users collection, and they do not share the client roster's rules:

• The user.list assistant tool (the tools API surface an AI chat can call) answers with what its caller is allowed to see: an admin caller gets full rows, any other caller gets the same public-identity projection useUsers() returns. A tool that reads users is not automatically the roster - check what it projects, and to whom, before you expose it to a model.
• Server actions bypass the projection entirely. Anything the worker calls with the X-App-Action header - server actions, cron jobs, chat-history helpers - reads full rows, email included, because the app's own server code is the trust boundary there. Never return a raw users row from an action to a caller without cutting it down yourself.

Roles vs. visibility#

It's tempting to model "private messages" via read: 'own', but 'own' only matches a single user. Every participant in a DM needs read access, but only that exact set - so reach for a participant-list pattern instead.

The built-in directory conversations schema does this out of the box: it declares collaboratorsField: 'ParticipantIds' and visibilityField: 'Visibility', with read: 'shared' on member. Setting a conversation's Visibility to 'private' and listing user IDs in ParticipantIds is then enough - the DO's canRead check filters every record before broadcast.

For CHANNELS_SCHEMA, the included type: 'public' | 'private' | 'dm' column is informational only - the schema's member permission is read: true, so the SDK does not gate channels by type on its own. If you need private channels, apply the same pattern: add a participants column, declare it as collaboratorsField, and switch read to 'shared' or 'collaborator'.

Debugging "why can't this user see X?"#

When a record isn't visible when you think it should be:

1. Check the caller's role. useAuth().userId gives you the user; useUsers().users.find(u => u.id === userId)?.role gives the role.
2. Check the rule for that role and operation. read: 'published' requires the record's visibilityField to match.
3. Check the envelope. record.createdBy is the 'own' check; record.data.<collaboratorsField> is the collaborator check.
4. Check the * rule. If the user is signed out (anonymous), only * applies.

Log the full record envelope locally to confirm the field values are what you expect.

Next steps#

• Schemas reference - full schema and permissions type signatures.
• Server actions - privileged writes that bypass user RBAC.