Introduction

Installation

Better Room uses your application’s copy of Better Auth, so it needs an existing Better Auth setup.

Yarn does not add peer dependencies for you. With Yarn, also run yarn add better-auth @better-auth/core better-call zod.

Setup

Add the plugin to your Better Auth instance, and its client plugin to your auth client.

Then run Better Auth’s migration or schema generation so the five room tables exist. Call betterRoom() once per betterAuth() instance: the code key is derived from the secret of the instance it first binds to.

The model

Five terms, resolved in one direction. Each depends only on the one before it.

1. Identity→
2. Actor→
3. Room→
4. Membership→
5. Access

Identity

Who someone is: a user and a session. Owned by Better Auth.

Actor

Whoever acts in a room. Anonymous, or the single actor a user owns. Owned by Better Room.

Room

A bounded context: active, locked or closed, with optional maxMembers and expiresAt. Owned by Better Room.

Membership

One actor in one room, with a role, an optional deadline, and leftAt or revokedAt once it ends. Owned by Better Room.

Access

Whether this actor may act here, now. Decided from the membership and the room when you ask. Owned by Better Room.

Roles are an open set of opaque strings. A join gets participant; any other role, such as facilitator, comes from addRoomMember on your server. room.createdBy is provenance and grants no authority: there is no host, only the roles your application names.

Joining is not authenticating

Better Auth establishes identity and sessions. Better Room resolves a code into a membership in one room. A caller with a session joins as their user’s actor; one without gets an anonymous actor and a signed grant cookie. Joining never creates a user.

When an anonymous member signs in, call promote so their memberships follow them to their account.

Room states

A room is active, locked or closed, and may carry a maxMembers and an expiresAt. A membership ends when its actor leaves, is revoked, or passes its own deadline.

active

Admits joins by code and additions.

locked

Refuses codes. Members stay; addRoomMember still adds.

closed

Ended for good. Cannot be undone or rotated.

past expiresAt

Not a stored status: the clock decides, so no write and no event marks it.

Leaving keeps the row and lets the same actor rejoin. Revoking is permanent. Show occupied from getRoomOccupancy as the number of people in a room, not room.memberCount, which is the admission gate and may sit above real occupancy after a write that failed halfway.

Capturing the code

Plaintext codes are returned only by createRoom and rotateRoomCode. No reversible copy exists anywhere, so if you drop one, the only way to get a working code for that room is to rotate. Four ways applications handle it, in rough order of how often they fit:

1. 1Return it to the creator. Hold it in client state while the waiting screen lives. Enough for a code read out loud.
2. 2Store it next to your room. Encrypted with a key you control, when a host must see the same code days later.
3. 3Rotate on demand. Show the new code. The previous one still admits for the grace window.
4. 4Share it at creation. Send it through your own link or invitation email and never persist it.

Operations

Self-service operations are routes, confined to the caller’s own actor, and grant nothing the caller did not already hold. The administrative operations are not routes at all: Better Auth never mounts them, a guessed path answers 404, and the client does not offer them. Your backend calls them through auth.api after deciding who may. createRoom is the one exception: it has a route, which refuses with CREATION_IS_SERVER_ONLY unless creation.overHttp is on.

Endpoints return reports, not rows. Each body is built field by field, so a column you add never leaks into a response. RoomReport, MembershipReport and their siblings are exported, and the client infers them.

Options

Every option is optional. These are the defaults.

Options are checked when betterRoom() runs: a number out of range throws a RangeError, and a flag that is not a real boolean, an unknown format or a reserved additionalFields name throws a TypeError. Every duration has a ceiling, because a value that overflows date arithmetic silently disables what it configures. crockford uses 32 symbols without look-alike letters and folds I and L to 1, O to 0; numeric is digits only, for keypads and phone prompts.

Connections

Commands travel over HTTP and live updates over your own socket. The plugin owns no transport. It gives you the two halves every integration needs: a way to authorize a connection, and a signal for every change.

Check the room when the connection opens, with the headers the upgrade carried. Cookies travel on a same-origin upgrade, so a grant and a session resolve exactly as they do over HTTP.

Authorization is decided when you ask, so a revoked member keeps a live socket until you close it. Keep each socket’s roomId and actorId, and close on the events that end access. A locked room keeps its members.

Events

onChange runs after every change the plugin saves, typed as RoomEvent. A switch on event.type narrows each one.

• Fires once per saved change, after the write, never for a refusal or a call that changed nothing.
• Runs in the process that handled the request, and the request waits for it. Hand slow work to a queue; with several instances, publish to your own broker.
• A listener that throws is logged and cannot undo the change or fail the request. Events are not retried.
• A deadline raises nothing when it passes. Schedule your own timer from expiresAt if clients must hear it at that moment.

Room codes

A room code is a secret that admits strangers. It is stored as an HMAC of its canonical form, keyed by a subkey derived from your Better Auth secret, so a database dump does not hand out a working key to every live room.

Presented

'k7qd-2m4p'

Canonical

'K7QD2M4P'

Identifier

hmac(subkey(secret), canonical)

Stored in

roomCode.identifier

Plaintext

never persisted

• Codes are folded through a fixed ASCII table, so case, spaces and dashes do not matter, and any other character is refused.
• Rotating keeps the previous code admitting for code.grace seconds, 120 by default. Only one generation is kept in grace.
• Over HTTP, a caller with no relation to a room gets the same answer whether it exists or not, so room ids cannot be walked.

Brute force and privilege

A failed code counts twice: against the caller’s address and against a global budget. An address that spends its own ceiling waits for its window to roll over. The global ceiling only gates an address with a failure of its own, so a flood cannot lock out callers who never guessed. There is no per-room lockout, because that would let anyone who knows a room exists lock its members out.

Every failure to resolve is the same CODE_DID_NOT_RESOLVE; telling them apart would roughly halve the work of sweeping the code space. Once a code resolves, the refusal names its reason, because the caller has already proved the code is good.

Error codes

Reachable as auth.$ERROR_CODES on the server and as ROOM_ERROR_CODES from both entry points. On the client, use ROOM_ERROR_CODES for values; client.$ERROR_CODES is for types only.

Database

Five tables, declared through Better Auth’s plugin schema, so the official migration and schema generators create them. Row ids are Better Auth’s to generate, so every generateId mode works.

roomActor

One per anonymous participant, or one per user. userId is unique and deliberately not a foreign key.

room

Status, memberCount gate, optional maxMembers and expiresAt, and createdBy as provenance.

roomCode

The HMAC in a unique identifier column, and a status that rotation walks.

roomMember

Unique on (roomId, actorId), so two simultaneous joins collapse into one.

roomAttempt

The brute-force budgets. Required: joining does not work without it.

Four unique indexes carry behaviour, not just speed: roomMember (roomId, actorId), roomCode.identifier, roomAttempt.key and roomActor.userId. Drizzle, Kysely and Better Auth’s Prisma generation emit them. A hand-written Prisma schema must carry all four, and on MongoDB the roomActor.userId index must be created by hand as a partial unique index. The full details live in the reference.

What Better Room deliberately doesn’t do

• Not An identity providerBetter Auth signs people in and owns users and sessions.
• Not A permission engineRoles are opaque strings. What each may do is your policy. Deferred, not rejected.
• Not A realtime serveronChange hands you each change. Connections, retries and fan-out stay yours.
• Not Roles carried by a codeA code admits as participant. Roles are assigned on the server.
• Not A reversible stored codeOnly an HMAC of the canonical code is kept.
• Not A per-room lockoutIt would let anyone who knows a room exists lock its members out.
• Not A metadata JSON columnAdd typed columns through schema additionalFields, or keep it in your own tables.