Authentication (guest and custom)
Shoehive works with no login at all: every visitor becomes a guest, and a signed resume
token brings them back as the same guest. When you have real accounts, an auth hook
replaces guest mode with your own identity. This page covers both.
Guests (the default)
Section titled “Guests (the default)”With no auth option, the first hello on a connection creates a guest: an id such as
g_... (128 random bits) and a name such as Guest k3x9. The server answers with a resume
token. The client stores it (in localStorage in a browser, in memory in Node) and sends it
on the next connection, so the same guest comes back. Every connection gets a fresh token with
a new expiry, so a player who keeps coming back never expires.
To pick the guest's first name, pass name to the client. See
Reconnects and sessions for storage and renaming.
import { createClient } from 'shoehive/client';
const client = createClient({ url: 'ws://localhost:3000/shoehive', name: 'Ada' });A missing, forged or expired token is not an error: the server simply creates a new guest, and
the client sees a different player.id in welcome. Tokens expire after resumeTokenTtlMs
(7 days by default).
The secret
Section titled “The secret”Resume tokens are signed with HMAC-SHA256. Set the key with the secret option or the
SHOEHIVE_SECRET environment variable. A key must be at least 32 bytes long, or
createServer throws.
import { createServer } from 'shoehive/server';
const shoehive = createServer({ games, // The first secret signs new tokens. Every secret verifies, so to rotate a key, // put the new one first and keep the old one until its tokens have expired. secret: [process.env.SHOEHIVE_SECRET_NEW!, process.env.SHOEHIVE_SECRET_OLD!],});- In production (
NODE_ENV=production, ordev: false) a guest server with no secret refuses to start. - In development the server makes up a random secret and logs a warning. Tokens then stop
working after a restart, so set
SHOEHIVE_SECRETwhen you want to test restart recovery. - There is no way to revoke one token. Replacing the secret revokes all of them.
Origins
Section titled “Origins”origins is an allowlist for the HTTP Origin header of the WebSocket upgrade. A request
from any other origin, or with no Origin header, is refused with HTTP 403; ['*'] accepts
any. Without it, guest servers accept any origin. With an auth hook in production, the
default is same-origin only: a page served from the same host as the socket may connect, and
others get 403, because a browser would otherwise send your site's cookies along with another
site's connection. Set origins when your web app is served from a different origin than the
socket.
import { createServer } from 'shoehive/server';
const shoehive = createServer({ games, origins: ['https://play.example.com'] });Guests and money
Section titled “Guests and money”A guest token is a bearer credential: whoever copies it from localStorage becomes that guest
until it expires. That is fine for a card game with friends and wrong for real money. If you
configure a wallet on a production server without an auth hook, Shoehive logs a warning at
startup. Use custom auth for anything with a balance.
Your own login
Section titled “Your own login”The auth hook runs once for every WebSocket upgrade, with the HTTP request (headers, cookies,
URL). Return a PlayerIdentity to let the connection in, or null to answer HTTP 401. If the
hook throws, the server logs the error and answers HTTP 500.
import { createServer } from 'shoehive/server';
const shoehive = createServer({ games, auth: async (req) => { const cookies = String(req.headers.cookie ?? ''); const session = /(?:^|; )session=([^;]+)/.exec(cookies)?.[1]; const account = await findAccount(session); if (!account) return null; // HTTP 401, no socket is opened return { id: account.id, name: account.displayName, metadata: { plan: account.plan }, }; },});What to know:
idis the player. It must be stable and unique: two connections that return the sameidare the same player, in several tabs, and they share seats.nameis shown to everyone at the table. It comes from your hook every time, soclient.rename()is refused withFORBIDDENfor authenticated players.metadatais any JSON. Shoehive keeps it with the stored session record (see Stores). It is not sent to clients and game code does not see it.- Resume tokens are ignored. The identity always comes from
auth, and the session is found byid, so a reconnect restores the same seats. The client still stores and sends the token. - Browsers cannot set headers on a WebSocket upgrade. Use a cookie (sent automatically to the same site), or a short-lived ticket in the URL that your app fetches first:
import { createClient } from 'shoehive/client';
declare const ticket: string;const client = createClient({ url: `wss://play.example.com/shoehive?ticket=${encodeURIComponent(ticket)}`,});On the server, read it with new URL(req.url ?? '/', 'http://localhost').searchParams.get('ticket').
Make a ticket valid for seconds and for one use, because URLs end up in logs. Do not put a
long-lived credential in the URL.
A client that gets the close code 4401 was unauthorized or revoked: it clears its stored
token and reconnects, and your hook then decides again.
Related
Section titled “Related”- Reconnects and sessions
- Wire protocol, section 2 (transport) and 4 (
hello) - ADR 0010: guest identity and resume tokens
