@streetmesh/hub 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 StreetMesh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,133 @@
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://protocol.streetmesh.com/brand/dark/svg/streetmesh-mark-dark.svg">
+  <img alt="StreetMesh" src="https://protocol.streetmesh.com/brand/svg/streetmesh-mark.svg" width="96">
+</picture>
+
+# StreetMesh Hub
+
+**The authoritative half of a venue: rooms, and who is allowed in them.**
+
+> Developed in [`Laravel`](https://github.com/StreetMesh/Laravel), at `hub/`,
+> and published here. Issues and pull requests belong there.
+>
+> Most people never install this. A venue builds its own hub out of it —
+> `php artisan hub:build` copies this in beside the rooms its experiences
+> ship, and rewrites the import. Installing it directly is for writing a room
+> against, and for reading.
+
+Anything people do together needs one place that decides what is true *right
+now* — whose turn it is, where the video is paused, what the current bid stands
+at. Not a place that collects opinions from the participants and takes the
+majority view: a place that decides, and refuses a browser saying otherwise,
+whether that browser is confused or lying.
+
+That is this. It is the only part of StreetMesh authoritative over the present
+moment, and it is not authoritative over anything else — what *happened* belongs
+to the venue, which signs the record, and to the person whose records it goes
+into.
+
+**Hub itself knows no rules.** It provides a room and a door. What makes a room
+a game of chess rather than a watch party is an experience, and experiences are
+somebody else's package.
+
+> Chess is the example used throughout this README, because it is the smallest
+> thing that needs the whole of it: two people, strict turns, a rule about what
+> is legal, and an outcome worth keeping afterwards. Where it is a poor guide,
+> the text says so — a watch party needs less than chess and an auction needs
+> more, and neither is built in here either.
+
+## What it knows, and what it deliberately does not
+
+Hub knows nothing about federation. It cannot resolve a handle, has never heard
+of a DID directory, and holds no permission over anybody's records.
+
+What it receives is a **ticket**: a short-lived assertion, signed by the venue
+with the key that venue already publishes, saying *this person may sit in this
+seat in this room*. Hub fetches the venue's DID document, checks a signature,
+and that is the whole of its security model.
+
+So it holds **no credential**. No shared secret, no private key, nothing to
+steal and nothing it could use to assert anything back to the venue. If this
+process were entirely compromised, what an attacker would gain is the ability to
+lie about what is happening in a room — not to forge a record, not to reach
+anybody's domicile, and not to impersonate the venue.
+
+```
+venue  ──signs a ticket──▶  browser  ──presents it──▶  hub
+                                                        │
+venue  ◀──── asks what happened, when it wants to ──────┘
+```
+
+Trust runs one way. Hub never calls the venue, never pushes, never asserts.
+
+## State, and what survives a restart
+
+**Hub is authoritative over the moment. The venue is authoritative over the
+record.**
+
+A room is a fast, rebuildable view of state the venue owns. Restart Hub and
+rooms reopen from the venue; something nobody is currently doing has no room at
+all. Which gives one rule an experience author has to think about:
+
+> Anything that must survive a restart has to reach the venue before it is
+> acknowledged to a participant.
+
+How much that costs depends entirely on what is being built, which is why it is
+declared rather than decided here:
+
+- a **watch party** can lose where the video was paused — everyone re-seeks, and
+  nothing was lost that anybody minded losing
+- an **auction** cannot lose a bid, ever, so every bid pays for a round trip
+  before the bidder is told it landed
+- **chess** sits between them, and even moves within itself: a fast game can
+  acknowledge here and persist a beat later, where a crash between the two costs
+  one move; a game played over days cannot afford that at all
+
+The framework asks an author which of those they are building, rather than
+choosing for them and being wrong most of the time.
+
+## Checking it
+
+```sh
+./check-ticket    # does a ticket PHP signed verify here?
+./check-join      # does it open a door, and does nothing else?
+./check-blip      # does an announcement over the shared secret land?
+./check-party     # can a table see that somebody is in a party?
+```
+
+The second matters because the first can pass while the room admits everybody
+anyway — a signature check being correct and a door being shut are two different
+properties, and only one of them keeps strangers out. `check-join` stands a real
+hub up and connects real websocket clients to it.
+
+`check-ticket` mints a real ticket in PHP and verifies it here, which is the
+seam least likely to be caught by either side's own tests. Between the two languages sit base58, a
+multicodec prefix, a compressed curve point whose y coordinate has to be
+recovered by solving the curve equation, base64url without padding, and an ECDSA
+signature as a raw r‖s pair rather than the DER most libraries hand you. A test
+written here that minted its own tickets would pass with every one of those
+wrong.
+
+It needs a StreetMesh server running locally — see
+[`Server`](https://github.com/StreetMesh/Server).
+
+**Node does not read the system keychain.** The script points it at Herd's
+certificate authority, because without that every fetch of a `.test` DID
+document fails and the failure looks exactly like a ticket that will not verify.
+That cost the prototype time twice, which is why it is a script rather than a
+command to remember.
+
+## Where this fits
+
+| Where | What it is |
+| --- | --- |
+| [**Glossary**](https://github.com/StreetMesh/Protocol/blob/main/GLOSSARY.md) | Every term here in plain words — venue, ticket, attestation, domicile — and whether each one is ours or borrowed. Start here if any of the above was unfamiliar. |
+| [<code>Protocol</code>](https://github.com/StreetMesh/Protocol) | What StreetMesh is. Guides, decisions, conformance vectors. |
+| [<code>Protocol&#8209;PHP</code>](https://github.com/StreetMesh/Protocol-PHP) | The framework-free implementation. |
+| [<code>Protocol&#8209;Laravel</code>](https://github.com/StreetMesh/Protocol-Laravel) | The same, bound to Laravel — including minting the tickets this checks. |
+| [<code>Server</code>](https://github.com/StreetMesh/Server) | Where to start if you want to run one. |
+| <code><b>Hub</b></code> | This. The authoritative multiplayer host. |
+
+## License
+
+MIT.

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@streetmesh/hub",
+  "version": "0.1.0",
+  "description": "The authoritative multiplayer host for a StreetMesh venue.",
+  "license": "MIT",
+  "type": "module",
+  "main": "src/mod.ts",
+  "exports": {
+    ".": "./src/mod.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "types:check": "tsc --noEmit",
+    "check:ticket": "./check-ticket",
+    "check:join": "./check-join",
+    "check:blip": "./check-blip",
+    "check:party": "./check-party"
+  },
+  "dependencies": {
+    "@colyseus/core": "^0.16.0",
+    "@colyseus/schema": "^3.0.0",
+    "@colyseus/tools": "^0.16.20",
+    "@colyseus/ws-transport": "^0.16.0",
+    "colyseus": "^0.16.0",
+    "express": "^5.2.1"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^22.10.0",
+    "colyseus.js": "^0.16.22",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/StreetMesh/Hub.git"
+  }
+}

package/src/announce.ts

@@ -0,0 +1,87 @@
+/**
+ * Telling a venue what happened in one of its rooms.
+ *
+ * The only thing this hub says unprompted. Everything else is the other way
+ * round — a ticket is signed by the venue and merely verified here, and a
+ * result is asked for rather than offered — and that asymmetry is deliberate:
+ * a hub that could assert things would be a hub a venue had to authenticate.
+ *
+ * Two things make asking impossible, and both happen when nobody is looking.
+ * A table empties, and the venue has no reason to ask. A game ends after both
+ * players have closed their tabs, and there is nobody left to knock — the room
+ * is disposed shortly afterwards and the result is gone for good.
+ *
+ * So: a shared secret, because a hub holds no key of its own. It is worth being
+ * plain about what that buys. The venue believes the state of a room it opened
+ * and the result of a game it started. Nothing here says who anybody is; that
+ * came from a ticket the venue signed and it does not come back this way.
+ */
+
+/**
+ * Where a venue is, worked out from the ticket that opened the room.
+ *
+ * Not configured. Every ticket names the venue that signed it — the hub already
+ * resolved that DID to fetch the key it verified with — so the address to call
+ * back on arrives with the authority to open the room in the first place.
+ *
+ * A hub serving several venues therefore cannot be talked into calling the
+ * wrong one, and an operator has one fewer setting to keep in step with
+ * reality.
+ */
+export function venueFor(issuer: string): string | null {
+  // did:web:games.example        → https://games.example
+  // did:web:games.example:venues:one → https://games.example/venues/one
+  if (!issuer.startsWith('did:web:')) {
+    return null
+  }
+
+  const [host, ...path] = issuer.slice('did:web:'.length).split(':').map(decodeURIComponent)
+
+  if (!host) {
+    return null
+  }
+
+  return path.length === 0 ? `https://${host}` : `https://${host}/${path.join('/')}`
+}
+
+export type Announcement = {
+  room: string
+  occupants: Array<{ name: string; seat: string }>
+  result?: Record<string, unknown> | null
+}
+
+/**
+ * Say it, and do not wait to be thanked.
+ *
+ * A venue that is down or slow must not hold up a room: the people in it are
+ * playing a game, and none of what is being said here is anything they are
+ * waiting on. A failure is logged and dropped — the venue asks for occupancy
+ * when it next needs it, and a result that did not arrive is one the next
+ * messenger carries.
+ */
+export async function announce(issuer: string, secret: string, what: Announcement): Promise<void> {
+  const venue = venueFor(issuer)
+
+  if (!venue || !secret) {
+    return
+  }
+
+  try {
+    const answer = await fetch(`${venue}/realtime`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${secret}`,
+      },
+      body: JSON.stringify(what),
+    })
+
+    if (!answer.ok && answer.status !== 404) {
+      // 404 is ordinary: a venue may have forgotten a gathering this is still
+      // holding. Anything else is worth seeing in a log.
+      console.warn(`[hub] ${venue} answered ${answer.status} about ${what.room}`)
+    }
+  } catch (unreachable) {
+    console.warn(`[hub] could not reach ${venue} about ${what.room}:`, (unreachable as Error).message)
+  }
+}

package/src/answers.ts

@@ -0,0 +1,133 @@
+/**
+ * What a venue may ask a hub about its own rooms.
+ *
+ * Two questions, and the venue has to know the name of the table to ask either.
+ * That name came from the venue in the first place — it minted the ticket — so
+ * nothing here is discoverable by somebody who did not already have it. There is
+ * deliberately no endpoint that lists anything: the prototype had one, and it
+ * published every live table to whoever asked.
+ */
+
+import type { Express, Request, Response } from 'express'
+
+/**
+ * Every room currently open, by the venue's name for it.
+ *
+ * The hub holds this because Colyseus does not: its own registry is keyed on
+ * the room id it invented, and the only name the venue knows is the one it put
+ * in the ticket. Kept here rather than in room metadata, which Colyseus
+ * publishes in a listing — a table's occupants are nobody else's business.
+ *
+ * One process. A hub spread across several would need this somewhere shared,
+ * and would need to say so rather than quietly answer "no such room" for half
+ * of them.
+ */
+const open = new Map<string, Resultful>()
+
+/**
+ * Only what this file needs of a room, so that rooms may import from here
+ * without this having to import them back.
+ */
+type Resultful = {
+  result(): Record<string, unknown> | null
+  present(): Array<{ name: string; seat: string }>
+}
+
+export function remember(room: Resultful, name: string): void {
+  open.set(name, room)
+}
+
+export function forget(name: string): void {
+  open.delete(name)
+}
+
+/**
+ * This process, distinct from any other serving the same name.
+ *
+ * A hub keeps its rooms in memory, so two processes behind one address are two
+ * hubs pretending to be one: people who joined the same table land in different
+ * rooms and cannot see each other. It is invisible from outside — every process
+ * answers every question plausibly — so this is here to make it countable. Ask
+ * for the build a few times; more than one answer means more than one hub.
+ */
+const process_id = Math.random().toString(36).slice(2, 8)
+
+/**
+ * Which build this hub is running.
+ *
+ * The venue generates the hub from what it has installed and knows the
+ * fingerprint of what it generated. Being able to ask a running hub the same
+ * question is what lets a deploy skip when nothing changed — and a hub restart
+ * ends every game in progress, so skipping is not a nicety.
+ *
+ * Unknown rather than absent when nothing set it. A hub started by hand is a
+ * legitimate thing to be; it simply cannot answer this.
+ */
+function answerBuild(_request: Request, response: Response): void {
+  response.json({ build: process.env.HUB_BUILD ?? 'unknown', process: process_id })
+}
+
+/**
+ * How a game ends up in somebody's own records.
+ *
+ * The venue asks; the hub answers only for a room that is over. The venue signs
+ * what comes back, which is why this is the one thing here worth being careful
+ * about: it is the hub's only influence on what gets written into a person's
+ * repository, and it cannot sign anything itself.
+ */
+function answerResult(request: Request, response: Response): void {
+  const room = open.get(String(request.query.room ?? ''))
+  const result = room?.result() ?? null
+
+  if (result === null) {
+    // No such table, or one still being played. Deliberately the same answer:
+    // whether a game exists is not a question this should help anybody explore.
+    response.status(404).json({})
+
+    return
+  }
+
+  response.json(result)
+}
+
+/**
+ * Who is actually at a table right now.
+ *
+ * The venue knows who sat down; only this knows who is still sitting there. A
+ * seat survives somebody closing the tab — it has to, or their opponent could
+ * take their chair while they reconnected — so a venue counting seats is
+ * counting a history rather than a room.
+ *
+ * Asked about named rooms and never listing them.
+ */
+function answerPresence(request: Request, response: Response): void {
+  const asked = request.query.room
+  const names = Array.isArray(asked) ? asked.map(String) : asked === undefined ? [] : [String(asked)]
+  const present: Record<string, Array<{ name: string; seat: string }>> = {}
+
+  for (const name of names) {
+    // Absent rather than empty for a room that is not open, so "nobody is
+    // there" and "there is no room" stay different answers.
+    const room = open.get(name)
+
+    if (room) {
+      present[name] = room.present()
+    }
+  }
+
+  response.json(present)
+}
+
+/**
+ * Bound onto the application the hub is already serving.
+ *
+ * Ordinary routes on an ordinary Express app, rather than a second HTTP server
+ * of our own. Being bespoke here bought nothing and cost the ability to change
+ * transport: WebTransport wants the Express application handed to it, and a
+ * bare `http.Server` is not one.
+ */
+export function routes(app: Express): void {
+  app.get('/build', answerBuild)
+  app.get('/result', answerResult)
+  app.get('/present', answerPresence)
+}

package/src/hub.ts

@@ -0,0 +1,87 @@
+/**
+ * What a StreetMesh hub is, said once.
+ *
+ * An ordinary Colyseus application — the options `@colyseus/tools` expects,
+ * which is the shape everything that deploys Colyseus expects. What makes it a
+ * hub rather than any other Colyseus server is two lines: the rooms a venue
+ * installed, and the two questions that venue may ask about them.
+ *
+ * One definition, used three times: by the venue's generated `app.config.ts`,
+ * by `hub-serve` locally, and by the checks in `bin/`. A hub assembled
+ * differently in a test than in production would be a hub whose tests prove
+ * something about a program nobody runs.
+ *
+ * Returns the options rather than calling `config()` on them. `config()`
+ * validates and hands back what it was given, and it belongs in the generated
+ * application next to `export default` — where every other Colyseus project
+ * puts it, and where anybody reading it will look for it.
+ */
+
+import { LocalDriver, LocalPresence } from '@colyseus/core'
+import type { ConfigOptions } from '@colyseus/tools'
+import { install, type Experience } from './install.ts'
+import { routes } from './answers.ts'
+
+/**
+ * Anything the operator wants on top of what a hub always does.
+ *
+ * `initializeTransport` is the one worth naming. Colyseus decides it when
+ * nothing says otherwise, which is what we want today — and WebTransport, when
+ * we come to try it, is this option and nothing else. Welding a transport in
+ * here is what the old hand-rolled server did, and it is what made the hub
+ * awkward to deploy and impossible to change.
+ */
+export type HubOptions = Omit<ConfigOptions, 'initializeGameServer' | 'initializeExpress'> & {
+  initializeGameServer?: ConfigOptions['initializeGameServer']
+  initializeExpress?: ConfigOptions['initializeExpress']
+}
+
+export function hub(experiences: Experience[], also: HubOptions = {}): ConfigOptions {
+  const { initializeGameServer, initializeExpress, options, ...rest } = also
+
+  return {
+    ...rest,
+
+    /*
+     * One process, said out loud.
+     *
+     * `@colyseus/tools` otherwise decides this by counting CPUs: more than one
+     * and it reaches for Redis, whether or not there is a Redis to reach. On a
+     * developer's machine that quietly works, because a development
+     * environment tends to be running one; somewhere else it quietly does not,
+     * and the symptom is two players in what looks like the same room who
+     * cannot see each other.
+     *
+     * A hub keeps its room registry in memory — see `answers.ts` — so one
+     * process is not a default, it is the assumption the design is built on.
+     * Spreading it across several needs that registry somewhere shared, and
+     * would be a decision with a Redis address attached rather than a
+     * consequence of how many cores somebody's machine has.
+     */
+    options: {
+      driver: new LocalDriver(),
+      presence: new LocalPresence(),
+      ...options,
+    },
+
+    initializeGameServer: (server) => {
+      /*
+       * Only what a venue installed.
+       *
+       * A party used to be defined here too, on the reasoning that it belongs
+       * to no experience and is therefore part of what a hub is. It is not:
+       * nothing about a party is state a room has to agree on or a rule a room
+       * has to enforce, which is all this process is for. It was here to answer
+       * who was present, and the venue answers that now on the poll that
+       * carries the handshake.
+       */
+      install(server, experiences)
+      initializeGameServer?.(server)
+    },
+
+    initializeExpress: (app) => {
+      routes(app)
+      initializeExpress?.(app)
+    },
+  }
+}

package/src/install.ts

@@ -0,0 +1,64 @@
+/**
+ * Putting an experience's rooms into a hub.
+ *
+ * A hub on its own does nothing useful — it has no rooms, because rooms are
+ * where the rules live and rules belong to experiences. So this takes them as
+ * an argument rather than discovering them: a venue knows what it has
+ * installed, and this does not need to.
+ *
+ * That is the seam. An experience ships a room; a venue collects the ones it
+ * has and hands them over; this puts them behind the same door.
+ */
+
+import type { Room, Server } from '@colyseus/core'
+
+/**
+ * A room class, as something that can be constructed.
+ *
+ * Colyseus has this type internally and does not export it from its package
+ * index, so it is written out here rather than reached for down a build path
+ * that is not ours to depend on. The constructor arguments are Colyseus's
+ * business, which is what the `any` says.
+ */
+export type RoomClass = new (...args: any[]) => Room
+
+export interface Experience {
+  /**
+   * The room type's name, as an NSID — `com.streetmesh.games.chess`.
+   *
+   * Named the way collections are, and for the same reason: whoever controls
+   * the domain controls the name, so two experiences by different authors
+   * cannot collide without somebody doing it on purpose.
+   */
+  name: string
+  room: RoomClass
+}
+
+/**
+ * The same name, in a form that survives being put in a URL.
+ *
+ * Colyseus asks for a room type by posting to `matchmake/create/{name}`, and a
+ * dot in that path is read as the start of a file extension — so an NSID
+ * arrives as `com` and nothing matches. Underscores are not legal in an NSID,
+ * which makes them a separator that can never collide with a real name and can
+ * always be undone.
+ *
+ * The NSID stays the name everywhere it matters: in tickets, in scopes, in
+ * collections. This is a transport detail and does not leak past this file.
+ */
+export function typeNameFor(nsid: string): string {
+  return nsid.replaceAll('.', '_')
+}
+
+/**
+ * Every experience this hub is to serve, defined on the game server.
+ *
+ * Filtered on the venue's room name, so everybody the venue sent to one table
+ * arrives in one room. Without it Colyseus would open a fresh room per person
+ * and two players would each be alone in their own game.
+ */
+export function install(server: Server, experiences: Experience[]): void {
+  for (const experience of experiences) {
+    server.define(typeNameFor(experience.name), experience.room).filterBy(['room'])
+  }
+}

package/src/mod.ts

@@ -0,0 +1,19 @@
+/**
+ * What an experience is given, and what a venue assembles a hub from.
+ *
+ * The public surface of this package, and deliberately small: a base room that
+ * has already dealt with who may be here, the shape of presence, and one
+ * definition of what a StreetMesh hub is. An experience writes rules and
+ * nothing else.
+ *
+ * There is no program in here any more. A hub is generated by the venue that
+ * runs it, because only a venue knows what it has installed — this package is
+ * the library that generated thing is built out of.
+ */
+
+export { VenueRoom, type JoinOptions, type Seated } from './room.ts'
+export { Occupant, Occupancy, type OccupantType, type OccupancyType } from './presence.ts'
+export { verifyTicket, type Ticket } from './ticket.ts'
+export { hub, type HubOptions } from './hub.ts'
+export { install, typeNameFor, type Experience, type RoomClass } from './install.ts'
+export { routes, remember, forget } from './answers.ts'

package/src/multikey.ts

@@ -0,0 +1,127 @@
+/**
+ * Reading a key the way a DID document writes one.
+ *
+ * A verification method publishes `publicKeyMultibase` — a string that says
+ * which curve it is and then the key, in one token. This turns that back into
+ * something WebCrypto will verify with.
+ *
+ * Only P-256 is read here, and deliberately so. It is what this project mints,
+ * it is what `did:plc` permits alongside secp256k1, and it is the one the
+ * platform can verify without a dependency. A document naming another curve is
+ * refused rather than guessed at.
+ */
+
+const BASE58 = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'
+
+/** The multicodec prefix for a P-256 public key, varint-encoded. */
+const P256_PREFIX = [0x80, 0x24]
+
+/**
+ * The prime the curve is defined over, and the parameters needed to recover a
+ * y coordinate from an x. A multikey holds the *compressed* point — x, plus one
+ * bit saying whether y is odd — so verifying means solving the curve equation
+ * for the y that was left out.
+ */
+const P = 2n ** 256n - 2n ** 224n + 2n ** 192n + 2n ** 96n - 1n
+const B = 0x5ac635d8aa3a93e7b3ebbd55769886bc651d06b0cc53b0f63bce3c3e27d2604bn
+
+function decodeBase58(input: string): Uint8Array {
+  let value = 0n
+
+  for (const character of input) {
+    const digit = BASE58.indexOf(character)
+
+    if (digit === -1) {
+      throw new Error(`[${input}] is not base58btc.`)
+    }
+
+    value = value * 58n + BigInt(digit)
+  }
+
+  const bytes: number[] = []
+
+  while (value > 0n) {
+    bytes.unshift(Number(value & 0xffn))
+    value >>= 8n
+  }
+
+  // Leading zero bytes encode as leading '1's and are lost by the arithmetic.
+  for (const character of input) {
+    if (character !== '1') break
+    bytes.unshift(0)
+  }
+
+  return Uint8Array.from(bytes)
+}
+
+/**
+ * y² = x³ - 3x + b, solved for y.
+ *
+ * The square root exists because p ≡ 3 (mod 4), which makes it a single
+ * exponentiation rather than anything iterative.
+ */
+function recoverY(x: bigint, odd: boolean): bigint {
+  const ySquared = (x ** 3n - 3n * x + B) % P
+  let y = modPow(ySquared, (P + 1n) / 4n, P)
+
+  if ((y % 2n === 1n) !== odd) {
+    y = P - y
+  }
+
+  if ((y * y - ySquared) % P !== 0n) {
+    throw new Error('That key is not a point on P-256.')
+  }
+
+  return y
+}
+
+function modPow(base: bigint, exponent: bigint, modulus: bigint): bigint {
+  let result = 1n
+  let b = base % modulus
+
+  for (let e = exponent; e > 0n; e >>= 1n) {
+    if (e & 1n) result = (result * b) % modulus
+    b = (b * b) % modulus
+  }
+
+  return result
+}
+
+function toBase64Url(value: bigint): string {
+  const hex = value.toString(16).padStart(64, '0')
+  const bytes = Uint8Array.from(hex.match(/../g)!.map((pair) => parseInt(pair, 16)))
+
+  return Buffer.from(bytes).toString('base64url')
+}
+
+/**
+ * A published key, as something that can check a signature.
+ */
+export async function importMultikey(multikey: string): Promise<CryptoKey> {
+  if (!multikey.startsWith('z')) {
+    throw new Error('A multikey is base58btc, which starts with z.')
+  }
+
+  const decoded = decodeBase58(multikey.slice(1))
+
+  if (decoded[0] !== P256_PREFIX[0] || decoded[1] !== P256_PREFIX[1]) {
+    throw new Error('That key is not on P-256, which is the only curve read here.')
+  }
+
+  const point = decoded.slice(2)
+
+  if (point.length !== 33) {
+    throw new Error('A compressed P-256 point is 33 bytes.')
+  }
+
+  const x = BigInt('0x' + Buffer.from(point.slice(1)).toString('hex'))
+  const y = recoverY(x, point[0] === 3)
+
+  return crypto.subtle.importKey(
+    'jwk',
+    { kty: 'EC', crv: 'P-256', x: toBase64Url(x), y: toBase64Url(y) },
+    { name: 'ECDSA', namedCurve: 'P-256' },
+    false,
+    ['verify'],
+  )
+}

package/src/presence.ts

@@ -0,0 +1,66 @@
+/**
+ * Who is in the room, as everybody in it sees them.
+ *
+ * The one piece of state every experience needs and none should have to write.
+ * A game wants to know when the second player arrives, a watch party wants to
+ * show a list, an auction wants to know who is still bidding — and all three
+ * are asking the same question.
+ *
+ * It is derived entirely from tickets, which means it is the venue's word
+ * rather than anybody's self-description. A participant cannot rename
+ * themselves here, cannot claim a seat they were not given, and cannot appear
+ * twice.
+ *
+ * Defined without decorators on purpose: decorators are not type syntax, so a
+ * file using them cannot be run by Node's own type stripping — and the checks
+ * in `bin/` do exactly that. This costs nothing and keeps one toolchain.
+ */
+
+import { MapSchema, schema } from '@colyseus/schema'
+
+export const Occupant = schema({
+  /** Their permanent identifier. Survives them changing their handle. */
+  did: 'string',
+
+  /** What to call them, as the venue vouched for it. */
+  name: 'string',
+
+  /**
+   * Which seat, where an experience has seats. Empty for the people a watch
+   * party would call an audience — present, but not playing.
+   */
+  seat: 'string',
+
+  /**
+   * The party this person is here with, or empty for somebody on their own.
+   *
+   * Here rather than kept to themselves, and that is the point of it. Somebody
+   * in a party has their voice superseded by the party's, which leaves them
+   * present in this room and unhearable in it — and a person who cannot be told
+   * that is a person talking to a wall without knowing why.
+   *
+   * It is also the only thing that makes a private channel legible to the
+   * people it is being used beside. A venue with parties on has decided to
+   * allow that; it has not decided to hide it.
+   *
+   * The party's room name rather than a flag, so two people can tell whether
+   * they are in the *same* one.
+   */
+  party: 'string',
+})
+
+export const Occupancy = schema({
+  /*
+   * Keyed by session rather than by DID, because one person may legitimately
+   * have two connections — a phone and a laptop — and the room has to be able
+   * to tell which one just went away.
+   */
+  occupants: { map: Occupant },
+})
+
+export type OccupantType = InstanceType<typeof Occupant>
+export type OccupancyType = InstanceType<typeof Occupancy>
+
+export function occupantsAsMap(): MapSchema<OccupantType> {
+  return new MapSchema<OccupantType>()
+}

package/src/room.ts

@@ -0,0 +1,336 @@
+/**
+ * A room nobody enters without a ticket.
+ *
+ * This is the base every experience builds on, and the only thing it knows how
+ * to do is check that a venue said somebody may sit down. It knows nothing
+ * about chess, or watch parties, or auctions — and nothing about federation
+ * either, which is the point: the venue resolved the address and checked the
+ * delegation, and all that arrives here is a signature.
+ *
+ * What an experience adds is rules. What it never has to add is any of this.
+ */
+
+import { Room, type Client } from '@colyseus/core'
+import { announce } from './announce.ts'
+import { forget, remember } from './answers.ts'
+import { verifyTicket, type Ticket } from './ticket.ts'
+import { Occupancy, Occupant, type OccupancyType } from './presence.ts'
+
+export interface Seated {
+  ticket: Ticket
+}
+
+/**
+ * Which room, in the venue's words.
+ *
+ * Not the same as Colyseus's `roomId`, which is generated here and means
+ * nothing to anybody else. The venue named this room when it minted the ticket,
+ * and that name is what the ticket is checked against — so it has to travel
+ * with the join and be held by the room.
+ */
+export interface JoinOptions {
+  ticket?: string
+  room?: string
+}
+
+/**
+ * What the room did, on one line each.
+ *
+ * A hub is the one part of this nobody can attach a debugger to: it runs
+ * somewhere else, and the questions it can be asked from outside are
+ * deliberately narrow. When two people who joined the same table cannot see
+ * each other, the thing worth knowing is whether they were ever in the same
+ * room — and the room is the only thing that knows.
+ *
+ * The Colyseus id as well as the venue's name for it, because the whole class
+ * of bug here is two rooms wearing one name.
+ */
+function note(what: string, room: { roomId: string; venueName: string; clients: unknown[] }): void {
+  console.log(`[room] ${what} ${room.venueName} as ${room.roomId} (${room.clients.length} here)`)
+}
+
+export abstract class VenueRoom<State extends OccupancyType = OccupancyType> extends Room<State> {
+  /**
+   * How long a table stays up with nobody at it.
+   *
+   * Colyseus disposes a room the moment it empties, which is right for a lobby
+   * and wrong for a game. A browser drops a socket for all sorts of reasons
+   * that are not somebody leaving — a reload, a navigation, a laptop lid, a
+   * connection that blinked — and if the table dies in that gap it takes the
+   * game with it. A new room then opens under the same name, so the venue and
+   * everybody else see a table that is fine and a game that never happened.
+   *
+   * Long enough to cover a reload and a bad minute of signal. Not so long that
+   * an abandoned table hangs around: the venue is told when this expires, and
+   * that is what settles a game nobody came back to.
+   */
+  private static readonly EMPTY_FOR_SECONDS = 120
+
+  private emptying: ReturnType<typeof setTimeout> | null = null
+
+  protected readonly seats = new Map<string, Ticket>()
+
+  /**
+   * Which seats the venue has filled, which is not the same as who is here.
+   *
+   * `seats` above is this room's own view, and it empties as people disconnect.
+   * This is the venue's, and it is the one an experience wants whenever the
+   * question is "are there two players" rather than "who can see this now".
+   *
+   * Added to and never subtracted from. Every ticket carries the venue's roster
+   * as it stood when it was signed, so the union of the tickets this room has
+   * seen is the fullest account it has — and a watcher's ticket, which names no
+   * seats at all, must not be able to empty a table.
+   */
+  protected readonly taken = new Set<string>()
+
+  /** The venue's name for this room, which every ticket must agree with. */
+  protected venueRoom = ''
+
+  /**
+   * The venue that signed the ticket that opened this room.
+   *
+   * Kept so the room can call back without being configured with an address —
+   * it arrives with the authority that opened the room, which means a hub
+   * serving several venues cannot be talked into telling the wrong one.
+   */
+  private issuer = ''
+
+  onCreate(options: JoinOptions): void {
+    if (typeof options?.room !== 'string' || options.room === '') {
+      throw new Error('A room has to be created under the name the venue gave it.')
+    }
+
+    this.venueRoom = options.room
+
+    /*
+     * Ours to close, not Colyseus's. See EMPTY_FOR_SECONDS.
+     */
+    this.autoDispose = false
+
+    /*
+     * An experience that wants state of its own sets it in `opened` and calls
+     * this first, or extends Occupancy. Either way presence is there before
+     * anybody can join, because the first join happens immediately after this
+     * returns.
+     */
+    if (!this.state) {
+      this.state = new Occupancy() as State
+    }
+
+    this.opened(options)
+
+    /*
+     * Findable by the name the venue knows it by. Colyseus keys rooms on an id
+     * it invented, and the venue only ever knew the name it put in the ticket —
+     * without this, a venue asking how a game ended has nothing to ask about.
+     */
+    remember(this, this.venueRoom)
+
+    note('opened', { roomId: this.roomId, venueName: this.venueRoom, clients: this.clients })
+  }
+
+  onDispose(): void {
+    if (this.emptying !== null) {
+      clearTimeout(this.emptying)
+      this.emptying = null
+    }
+
+    note('disposed', { roomId: this.roomId, venueName: this.venueRoom, clients: this.clients })
+
+    forget(this.venueRoom)
+
+    /*
+     * The last word. A room is memory, and after this there is nobody left to
+     * ask — a game that ended once both players had closed their tabs would
+     * otherwise be a result nobody ever hears, and a table nobody is at would
+     * go on being counted until the venue's own cache gave up.
+     */
+    this.tell()
+  }
+
+  /**
+   * Tell the venue what this room looks like now.
+   *
+   * Called here whenever somebody arrives or leaves. An experience whose state
+   * changes in a way the venue needs to know about — a game ending, which
+   * nobody is leaving over — calls it too.
+   *
+   * Not awaited anywhere. The people in this room are playing a game and none
+   * of them are waiting on the venue hearing about it, so a venue that is slow
+   * or down must not hold anything up.
+   */
+  protected tell(): void {
+    void announce(this.issuer, process.env.STREETMESH_REALTIME_SECRET ?? '', {
+      room: this.venueRoom,
+      occupants: this.present(),
+      result: this.result(),
+    })
+  }
+
+  /**
+   * Called before a client is admitted, and a throw here is a refusal rather
+   * than an error — which is why everything deciding whether somebody may be
+   * here belongs in it rather than in `onJoin`.
+   */
+  async onAuth(client: Client, options: JoinOptions): Promise<Seated> {
+    if (typeof options?.ticket !== 'string' || options.ticket === '') {
+      throw new Error('A seat here needs a ticket from the venue.')
+    }
+
+    /*
+     * Compared against the name this room was opened under, never against the
+     * name in the ticket itself. A ticket that vouched for its own room would
+     * open any room it was pointed at.
+     */
+    const ticket = await verifyTicket(options.ticket, this.venueRoom)
+
+    /*
+     * One seat, one occupant — but the occupant is a person, not a connection.
+     *
+     * A second connection from the same person takes the chair over rather than
+     * being refused. Refusing was wrong in every case it actually came up: a
+     * tab that crashed, a laptop that slept, a browser that navigated without
+     * unloading the page. In all of them the old socket is still holding a seat
+     * nobody is sitting in, and the person it belongs to cannot get back to
+     * their own game until it times out.
+     *
+     * Two connections *are* still one occupant. The old one is shown the door
+     * here, so the two can never disagree about the room.
+     */
+    this.replace(ticket.subject)
+
+    return { ticket }
+  }
+
+  /**
+   * Show somebody's earlier connection the door, if they have one.
+   *
+   * Cleared here as well as in `onLeave`, rather than waiting for it: the new
+   * client is admitted immediately after this returns, and a seat still listed
+   * under the old session would be a room that briefly holds the same person
+   * twice.
+   */
+  private replace(subject: string): void {
+    for (const [sessionId, seated] of this.seats) {
+      if (seated.subject !== subject) {
+        continue
+      }
+
+      this.seats.delete(sessionId)
+      this.state.occupants.delete(sessionId)
+
+      // 4103: taken over from somewhere else. A code rather than a silent
+      // close, so the older screen can say so instead of looking broken.
+      this.clients.find((client) => client.sessionId === sessionId)?.leave(4103)
+    }
+  }
+
+  onJoin(client: Client, options: JoinOptions, auth: Seated): void {
+    this.seats.set(client.sessionId, auth.ticket)
+    this.issuer ||= auth.ticket.issuer
+
+    for (const seat of auth.ticket.taken) {
+      this.taken.add(seat)
+    }
+
+    this.state.occupants.set(
+      client.sessionId,
+      new Occupant({
+        did: auth.ticket.subject,
+        name: auth.ticket.name,
+        seat: auth.ticket.seat,
+        party: auth.ticket.party,
+      }),
+    )
+
+    this.seated(client, auth.ticket)
+
+    /*
+     * Somebody is here, so the table is not closing. This is the ordinary case
+     * after a reload: the same person, seconds later, and nothing was lost.
+     */
+    if (this.emptying !== null) {
+      clearTimeout(this.emptying)
+      this.emptying = null
+    }
+
+    note(`joined ${auth.ticket.name} (${auth.ticket.seat})`, {
+      roomId: this.roomId,
+      venueName: this.venueRoom,
+      clients: this.clients,
+    })
+
+    this.tell()
+  }
+
+  /**
+   * What this room will say happened, once it is over.
+   *
+   * Null while there is still a game on, and null forever in a room that has
+   * no notion of an ending. A venue asks for this to write somebody a record,
+   * so answering early would be the venue signing a result that had not
+   * happened yet.
+   *
+   * Deliberately plain data. The venue signs whatever comes back, so it must
+   * be something it can hand to a repository unchanged.
+   */
+  result(): Record<string, unknown> | null {
+    return null
+  }
+
+  /**
+   * Who is connected right now, and what they are sitting in.
+   *
+   * Not who has a seat — that is the venue's record and outlives a dropped
+   * connection on purpose. This is the room.
+   */
+  present(): Array<{ name: string; seat: string }> {
+    return [...this.seats.values()].map((ticket) => ({
+      name: ticket.name,
+      seat: ticket.seat,
+    }))
+  }
+
+  onLeave(client: Client): void {
+    const ticket = this.seats.get(client.sessionId)
+
+    this.seats.delete(client.sessionId)
+    this.state.occupants.delete(client.sessionId)
+
+    if (ticket) {
+      this.left(client, ticket)
+    }
+
+    note(`left ${ticket?.name ?? 'somebody'}`, {
+      roomId: this.roomId,
+      venueName: this.venueRoom,
+      clients: this.clients,
+    })
+
+    this.tell()
+
+    if (this.clients.length === 0) {
+      this.emptying = setTimeout(() => {
+        note('closing, nobody came back', {
+          roomId: this.roomId,
+          venueName: this.venueRoom,
+          clients: this.clients,
+        })
+
+        this.disconnect()
+      }, VenueRoom.EMPTY_FOR_SECONDS * 1000)
+    }
+  }
+
+  /** Who is here, as the venue vouched for them. */
+  protected occupants(): Ticket[] {
+    return [...this.seats.values()]
+  }
+
+  protected opened(options: JoinOptions): void {}
+
+  protected seated(client: Client, ticket: Ticket): void {}
+
+  protected left(client: Client, ticket: Ticket): void {}
+}

package/src/ticket.ts

@@ -0,0 +1,239 @@
+/**
+ * A permission slip to sit somewhere.
+ *
+ * The venue has already done everything hard: resolved a federated address,
+ * checked a delegation, decided who sits in which seat. This half can do none
+ * of that and never needs to. It receives an assertion signed with the venue's
+ * own key — the same key already published in its DID document — and has only
+ * to check a signature.
+ *
+ * That is why there is no shared secret on the join path, and why this process
+ * holds no credential of any kind. It cannot impersonate the venue, cannot be
+ * stolen from usefully, and cannot assert anything back: everything it knows
+ * arrived signed by somebody else.
+ */
+
+import { importMultikey } from './multikey.ts'
+
+export interface Ticket {
+  /** The venue that issued it, as a DID. */
+  issuer: string
+  /** Who is sitting down, as a DID. */
+  subject: string
+  /** What to call them on screen. The venue's word, not theirs. */
+  name: string
+  /** Which room, and which seat in it. */
+  room: string
+  seat: string
+  /**
+   * Every seat the venue has filled, including this one.
+   *
+   * The venue's record rather than this room's — somebody who has closed their
+   * tab still holds their chair. Nothing here can work this out: a room sees
+   * connections, and a connection is not a seat.
+   */
+  taken: string[]
+  /**
+   * The room name of the party this person is here with, or empty.
+   *
+   * The venue's word, like everything else on a ticket. A browser that could
+   * say which party it was in would be a browser that could put itself in
+   * somebody else's.
+   */
+  party: string
+}
+
+interface Cached {
+  keys: Map<string, CryptoKey>
+  until: number
+}
+
+/**
+ * Documents are cached briefly, because a key rotation must actually take
+ * effect. Long enough that a room filling up does not re-fetch per person;
+ * short enough that a retired key stops working in minutes rather than at the
+ * next restart.
+ */
+const DOCUMENT_SECONDS = 300
+
+const documents = new Map<string, Cached>()
+
+/**
+ * `did:web` only, and that is a deliberate limit for now.
+ *
+ * The identifier *is* the address, so resolving it needs nothing but a fetch.
+ * `did:plc` would mean talking to a directory, which is a dependency this
+ * process does not need in order to check that a venue signed something —
+ * venues are servers with hostnames, which is exactly what `did:web` is for.
+ */
+function documentUrl(did: string): string {
+  if (!did.startsWith('did:web:')) {
+    throw new Error(`[${did}] is not a did:web identifier, which is all this reads.`)
+  }
+
+  const [host, ...path] = did.slice('did:web:'.length).split(':').map(decodeURIComponent)
+
+  return path.length === 0
+    ? `https://${host}/.well-known/did.json`
+    : `https://${host}/${path.join('/')}/did.json`
+}
+
+async function keysFor(did: string, now: number): Promise<Map<string, CryptoKey>> {
+  const held = documents.get(did)
+
+  if (held && held.until > now) {
+    return held.keys
+  }
+
+  const response = await fetch(documentUrl(did))
+
+  if (!response.ok) {
+    throw new Error(`[${did}] published no document we could read.`)
+  }
+
+  const document = (await response.json()) as {
+    id?: string
+    verificationMethod?: { id?: string; publicKeyMultibase?: string }[]
+  }
+
+  /*
+   * A document reached at the right address that names somebody else is not
+   * that identity's document, however it was reached.
+   */
+  if (document.id !== did) {
+    throw new Error(`The document at ${documentUrl(did)} claims to be [${document.id}].`)
+  }
+
+  const keys = new Map<string, CryptoKey>()
+
+  for (const method of document.verificationMethod ?? []) {
+    if (method.id && method.publicKeyMultibase) {
+      keys.set(method.id, await importMultikey(method.publicKeyMultibase))
+    }
+  }
+
+  documents.set(did, { keys, until: now + DOCUMENT_SECONDS * 1000 })
+
+  return keys
+}
+
+/**
+ * One segment of a compact JWS, read as JSON.
+ *
+ * Anything at all can arrive at this door, so a segment that is not base64url
+ * or not JSON is an ordinary refusal rather than something to throw a parser
+ * error about. Letting one escape would report "unexpected token" to somebody
+ * whose actual problem is that they have no ticket.
+ */
+function readSegment(segment: string, called: string): unknown {
+  let decoded: string
+
+  try {
+    decoded = Buffer.from(segment, 'base64url').toString()
+  } catch {
+    throw new Error(`That ticket's ${called} is not base64url.`)
+  }
+
+  try {
+    const parsed: unknown = JSON.parse(decoded)
+
+    if (parsed === null || typeof parsed !== 'object') {
+      throw new Error('not an object')
+    }
+
+    return parsed
+  } catch {
+    throw new Error(`That ticket's ${called} is not readable.`)
+  }
+}
+
+/**
+ * Check a ticket, and say who it seats.
+ *
+ * @param expectedRoom the room actually being joined, which is not the same as
+ *                     the room the ticket names until it has been compared
+ */
+export async function verifyTicket(
+  compact: string,
+  expectedRoom: string,
+  now: number = Date.now(),
+): Promise<Ticket> {
+  const [header, payload, signature] = compact.split('.')
+
+  if (!header || !payload || !signature) {
+    throw new Error('That is not a compact JWS.')
+  }
+
+  const head = readSegment(header, 'header') as { alg?: string; kid?: string }
+
+  /*
+   * Pinned to what we are willing to check, never to what the document asks
+   * for. Accepting an algorithm named in an unverified header is the classic
+   * JOSE footgun — it lets a document choose how it will be checked.
+   */
+  if (head.alg !== 'ES256') {
+    throw new Error(`That ticket is signed with [${head.alg}], which is not accepted here.`)
+  }
+
+  if (!head.kid) {
+    throw new Error('That ticket names no key.')
+  }
+
+  const issuer = head.kid.split('#')[0]
+  const keys = await keysFor(issuer, now)
+  const key = keys.get(head.kid)
+
+  if (!key) {
+    throw new Error(`[${issuer}] does not publish a key called [${head.kid}].`)
+  }
+
+  const verified = await crypto.subtle.verify(
+    { name: 'ECDSA', hash: 'SHA-256' },
+    key,
+    Buffer.from(signature, 'base64url'),
+    Buffer.from(`${header}.${payload}`),
+  )
+
+  if (!verified) {
+    throw new Error('That ticket does not verify against the key it names.')
+  }
+
+  const claims = readSegment(payload, 'claims') as Record<string, unknown>
+
+  if (typeof claims.exp !== 'number' || claims.exp * 1000 < now) {
+    throw new Error('That ticket has expired.')
+  }
+
+  /*
+   * The room is compared rather than trusted. A ticket is issued for one place,
+   * and without this a ticket for a table anybody may sit at would open every
+   * room on the server.
+   */
+  if (claims.room !== expectedRoom) {
+    throw new Error(`That ticket is for [${String(claims.room)}], not [${expectedRoom}].`)
+  }
+
+  if (typeof claims.sub !== 'string' || claims.sub === '') {
+    throw new Error('That ticket seats nobody.')
+  }
+
+  return {
+    issuer,
+    subject: claims.sub,
+    name: typeof claims.name === 'string' ? claims.name : claims.sub,
+    room: expectedRoom,
+    seat: typeof claims.seat === 'string' ? claims.seat : '',
+
+    /*
+     * Absent on a ticket signed before venues said this, which is an empty
+     * roster rather than a refusal — an older venue is not a broken one.
+     */
+    taken: Array.isArray(claims.taken) ? claims.taken.filter((seat) => typeof seat === 'string') : [],
+
+    /*
+     * Absent on a ticket from a venue that does not do parties, which is
+     * nobody's party rather than a refusal — the same reading `taken` gets.
+     */
+    party: typeof claims.party === 'string' ? claims.party : '',
+  }
+}