@hadoku/rooms-protocol 0.0.0-stage → 0.43.15

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Matthaeus Wolff
+
+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/dist/game-bundle.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The game-bundle contract: how a room host mounts a game it knows nothing
+ * about.
+ *
+ * A host (watchparty's room) holds a list of `GameEntry` rows as DATA. For a
+ * `module` entry it dynamically imports `url`, expects the module to export
+ * `mount` (a `GameBundleModule`), and hands it an element plus a context. The
+ * bundle renders into that element — inside its own shadow root, so neither
+ * side's styles reach the other — and talks to its own server; the host only
+ * relays who is looking, what theme they are in, and whether they lead.
+ *
+ * Adding a game is therefore a data edit on the host, never host code.
+ * `iframe` is the one built-in kind: the host's own cross-origin iframe game
+ * (Bomberman), kept as it was.
+ */
+/** Who is viewing. The same values the embeddable room chrome receives. */
+export interface GameBundleIdentity {
+    /** The viewer's key-registry userId when known, else `public`. A host
+     *  never hands a bundle the session id: it is a bearer credential. */
+    userId: string;
+    userType: string;
+    /** Display name, or null when the viewer has none yet. */
+    name: string | null;
+}
+export interface GameBundleContext {
+    /** The room the bundle is mounted in: the same value for every
+     *  participant. It is the room's id, not the key a viewer joined with —
+     *  a leader joins with a different key, and that key is a credential a
+     *  bundle must never be handed. */
+    roomKey: string;
+    identity: GameBundleIdentity;
+    /** The current hadoku theme name. */
+    theme: string;
+    isLeader: boolean;
+    /** Ask the host to close the bundle. For the leader this closes it for
+     *  everyone; for anyone else it closes it for them only. */
+    close(): void;
+}
+export interface MountedGameBundle {
+    /** Tear down everything `mount` created. Called once. */
+    unmount(): void;
+    /** The context changed (theme, identity, leadership). */
+    update(ctx: GameBundleContext): void;
+}
+/** What a `module` entry's URL must export. */
+export interface GameBundleModule {
+    mount(el: HTMLElement, ctx: GameBundleContext): MountedGameBundle | Promise<MountedGameBundle>;
+}
+export type GameEntry = 
+/** The host's built-in iframe game. */
+{
+    id: string;
+    name: string;
+    cover?: string;
+    kind: 'iframe';
+}
+/** An ES module exporting `GameBundleModule`, at a same-origin path. */
+ | {
+    id: string;
+    name: string;
+    cover?: string;
+    kind: 'module';
+    url: string;
+};
+/**
+ * Whether `value` is a module that satisfies `GameBundleModule`. A bundle is
+ * loaded from a URL at runtime, so its shape is a claim the host checks rather
+ * than a type it can trust.
+ */
+export declare function isGameBundleModule(value: unknown): value is GameBundleModule;
+/** Whether `value` is what a bundle's `mount` must resolve to. */
+export declare function isMountedGameBundle(value: unknown): value is MountedGameBundle;
+//# sourceMappingURL=game-bundle.d.ts.map

package/dist/game-bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"game-bundle.d.ts","sourceRoot":"","sources":["../src/game-bundle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,2EAA2E;AAC3E,MAAM,WAAW,kBAAkB;IACjC;0EACsE;IACtE,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC;;;uCAGmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;IAClB;gEAC4D;IAC5D,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,yDAAyD;IACzD,OAAO,IAAI,IAAI,CAAC;IAChB,yDAAyD;IACzD,MAAM,CAAC,GAAG,EAAE,iBAAiB,GAAG,IAAI,CAAC;CACtC;AAED,+CAA+C;AAC/C,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,EAAE,WAAW,EAAE,GAAG,EAAE,iBAAiB,GAAG,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAChG;AAED,MAAM,MAAM,SAAS;AACnB,uCAAuC;AACrC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE;AAC9D,wEAAwE;GACtE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9E;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAG5E;AAED,kEAAkE;AAClE,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAI9E"}

package/dist/game-bundle.js

@@ -0,0 +1,30 @@
+/**
+ * The game-bundle contract: how a room host mounts a game it knows nothing
+ * about.
+ *
+ * A host (watchparty's room) holds a list of `GameEntry` rows as DATA. For a
+ * `module` entry it dynamically imports `url`, expects the module to export
+ * `mount` (a `GameBundleModule`), and hands it an element plus a context. The
+ * bundle renders into that element — inside its own shadow root, so neither
+ * side's styles reach the other — and talks to its own server; the host only
+ * relays who is looking, what theme they are in, and whether they lead.
+ *
+ * Adding a game is therefore a data edit on the host, never host code.
+ * `iframe` is the one built-in kind: the host's own cross-origin iframe game
+ * (Bomberman), kept as it was.
+ */
+/**
+ * Whether `value` is a module that satisfies `GameBundleModule`. A bundle is
+ * loaded from a URL at runtime, so its shape is a claim the host checks rather
+ * than a type it can trust.
+ */
+export function isGameBundleModule(value) {
+    return typeof value === 'object' && value !== null
+        && typeof value.mount === 'function';
+}
+/** Whether `value` is what a bundle's `mount` must resolve to. */
+export function isMountedGameBundle(value) {
+    return typeof value === 'object' && value !== null
+        && typeof value.unmount === 'function'
+        && typeof value.update === 'function';
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @wolffm/rooms-protocol — the wire contract for rooms.
+ *
+ * Deliberately dependency-free (not even zod yet) and free of any hosting
+ * app's vocabulary: no playhead, media, fragment, playlist, tierlist or
+ * sprite. Both `rooms-server` and a client bind to this, so anything that
+ * lands here becomes a promise to every consumer.
+ *
+ * Extracted from watchparty's `@watchparty/shared`, which keeps re-exporting
+ * these so the ~40 existing import sites did not all have to move in the same
+ * commit as the package boundary.
+ */
+export * from './participantId.js';
+export * from './seats.js';
+export * from './resync.js';
+export * from './game-bundle.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,cAAc,oBAAoB,CAAC;AACnC,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,16 @@
+/**
+ * @wolffm/rooms-protocol — the wire contract for rooms.
+ *
+ * Deliberately dependency-free (not even zod yet) and free of any hosting
+ * app's vocabulary: no playhead, media, fragment, playlist, tierlist or
+ * sprite. Both `rooms-server` and a client bind to this, so anything that
+ * lands here becomes a promise to every consumer.
+ *
+ * Extracted from watchparty's `@watchparty/shared`, which keeps re-exporting
+ * these so the ~40 existing import sites did not all have to move in the same
+ * commit as the package boundary.
+ */
+export * from './participantId.js';
+export * from './seats.js';
+export * from './resync.js';
+export * from './game-bundle.js';

package/dist/participantId.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Participant identity — the FORMAT half (pure, isomorphic, zero deps).
+ *
+ * A `ParticipantId` names a *person in a room*, and it is deliberately NOT the
+ * socket id. Until this module existed, `clientId` WAS `socket.id`
+ * (`ws/join.ts`), so every identity in the system died on reconnect and the
+ * codebase carried three separate workarounds for it: the `fk:`/`cid:` name
+ * persistence keys in `rooms/store.ts`, the A/B bucketing that had to abandon
+ * `me.clientId` for a persisted localStorage id (`lib/fragmentDelivery.ts`),
+ * and the leader-takeover heuristics in `ws/join.ts` that exist to recognise a
+ * refreshing presenter whose new socket is a different "client".
+ *
+ * ## The tier is IN the id, on purpose
+ *
+ *   fk:<digest>    account  — derived from the platform ACCOUNT id (the key
+ *                             registry's `userId`, resolved server-side through
+ *                             whoami). Survives reconnects, reloads, restarts,
+ *                             devices, networks — and KEY ROTATION. The `fk`
+ *                             spelling predates that and is kept because
+ *                             consumers parse it; read it as "account".
+ *
+ * ## Derive the account tier from the userId, never from the key
+ *
+ * The X-User-Key is a CREDENTIAL and it rotates. An id hashed from it changes
+ * the moment the key does, and everything keyed on the id — a remembered seat,
+ * a restored name, the same-presenter leader takeover — silently stops
+ * recognising the person. That is the same failure that detached every
+ * tierlist ballot in watchparty (#144), one layer up. `accountId` is the
+ * input; `friendKey` remains accepted ONLY so a consumer that has not yet
+ * resolved userIds keeps working, and loses rotation-stability while it does.
+ *   dev:<digest>   device   — derived from a browser-persisted id. Survives a
+ *                             reload and a reconnect; not a new browser.
+ *   eph:<socketId> ephemeral— anon with no usable storage. Dies with the socket.
+ *
+ * Encoding durability in the id means code that REQUIRES durability can assert
+ * on it (`requireDurable`) instead of hoping. A 45-minute draft seat can demand
+ * `account` or `device`; a demo room can accept `ephemeral`.
+ *
+ * ## `device` is NOT an authorization boundary
+ *
+ * The device id is **client-asserted** — it arrives in the join payload and
+ * nothing proves it. So a `dev:` identity is good enough to carry a display
+ * name or hold a seat among friends, and NOT good enough to gate a capability:
+ * anyone who learns another client's device id can present it. Only the
+ * `account` tier is server-authenticated (the edge resolves the hadoku_session
+ * cookie into X-User-Key; the browser never sees the key). Anything that grants
+ * power — leadership, ownership, a moderation action — must require
+ * `account`. `isAuthenticatedTier` is the check; do not widen it.
+ *
+ * ## Why the id can be logged and put on the wire
+ *
+ * The `fk:` and `dev:` bodies are non-reversible digests, not the source
+ * material (see the server's `deriveParticipantId`, which owns the hashing
+ * because it needs a synchronous crypto primitive this package cannot assume).
+ * The friend key IS the X-User-Key credential, so embedding it raw would hand
+ * every viewer everyone else's key while looking entirely normal on screen —
+ * the same trap `opaqueVoterId` was written to avoid in `tierlist/store.ts`.
+ * Hashing at derivation means there is exactly ONE id per participant rather
+ * than an internal id plus a wire handle to keep in sync.
+ */
+/** Durability class of a participant identity. Ordered least → most durable. */
+export type ParticipantIdTier = 'ephemeral' | 'device' | 'account';
+/** `fk:…` | `dev:…` | `eph:…` — see this module's header. */
+export type ParticipantId = string;
+export declare const PARTICIPANT_ID_PREFIX: Readonly<Record<ParticipantIdTier, string>>;
+/**
+ * Shortest friend key we treat as real. Matches the existing `>= 5` checks in
+ * `ws/handlers.ts` and `rooms/store.ts#hasFriendKey` — keep them in step.
+ */
+export declare const MIN_FRIEND_KEY_LENGTH = 5;
+/**
+ * Shortest device id we accept. Longer than the friend-key floor on purpose:
+ * a friend key is server-injected and known-good, while a device id is
+ * client-asserted, so a short one is far more likely to be junk (or a
+ * collision-farming attempt) than a real persisted id. Clients that can't do
+ * better fall through to `ephemeral`, which is honest rather than broken.
+ */
+export declare const MIN_DEVICE_ID_LENGTH = 8;
+/** Hex digest length used by the `account` and `device` bodies. */
+export declare const PARTICIPANT_ID_DIGEST_LENGTH = 16;
+/**
+ * Tier of an id, or `null` if it isn't one. Returns null rather than throwing
+ * or defaulting: an unrecognised id is absence of evidence, and defaulting it
+ * to `ephemeral` would silently admit a malformed id to every path that only
+ * refuses `ephemeral` — the failure would look like a working downgrade.
+ */
+export declare function participantIdTier(id: string): ParticipantIdTier | null;
+/** True for a well-formed id of any tier. */
+export declare function isParticipantId(id: string): boolean;
+/**
+ * Survives a reconnect (`account` or `device`). This is the check for "may hold
+ * a seat / may have a pending request replayed", NOT for "may do something
+ * privileged" — see `isAuthenticatedTier`.
+ */
+export declare function isDurableParticipantId(id: string): boolean;
+/**
+ * Server-authenticated identity (`account` only). The gate for anything that
+ * grants power. Deliberately narrower than `isDurableParticipantId` because a
+ * device id is client-asserted — see this module's header.
+ */
+export declare function isAuthenticatedTier(id: string): boolean;
+/** Rank comparison — `tierAtLeast(id, 'device')` admits device and account. */
+export declare function participantTierAtLeast(id: string, minTier: ParticipantIdTier): boolean;
+/**
+ * Whether a friend key is long enough to be treated as real. THE one
+ * definition — it was hand-copied as `length >= 5` across six files, which is
+ * how one of them ends up disagreeing with the rest.
+ *
+ * A type guard, so callers narrow instead of re-asserting with a cast.
+ */
+export declare function isUsableFriendKey(friendKey: unknown): friendKey is string;
+/**
+ * Whether a platform account id (the registry `userId`) is usable. Same floor
+ * as a friend key: it is server-resolved, never client-asserted, so the check
+ * exists only to reject an empty or junk value, not to judge trust.
+ */
+export declare function isUsableAccountId(accountId: unknown): accountId is string;
+/** Whether a client-supplied device id is long enough to be treated as real. */
+export declare function isUsableDeviceId(deviceId: unknown): deviceId is string;
+/**
+ * Which tier a set of inputs WOULD produce, without needing the hash. Lets the
+ * join path log and gate on the tier before (or without) deriving the id, and
+ * lets tests assert the tier decision independently of the digest.
+ */
+export declare function resolveParticipantTier(input: {
+    accountId?: string | null;
+    friendKey?: string | null;
+    deviceId?: string | null;
+}): ParticipantIdTier;
+/**
+ * Assemble an id from an already-computed body. The server's
+ * `deriveParticipantId` is the only intended caller for the hashed tiers; it is
+ * exported so both halves share one spelling of the prefixes rather than
+ * concatenating them by hand at each site.
+ */
+export declare function formatParticipantId(tier: ParticipantIdTier, body: string): ParticipantId;
+/**
+ * The body after the scheme, or `null` for a malformed id. Useful for logs
+ * that want a short handle without the prefix noise; never for reconstructing
+ * the source material, which is not recoverable from a digest.
+ */
+export declare function participantIdBody(id: string): string | null;
+/** How much of a participant's body a handle shows. */
+export declare const PARTICIPANT_HANDLE_LENGTH = 6;
+/**
+ * A short, wire-safe handle for a participant — what you may SHOW a room.
+ *
+ * The one part of an identity that is safe to put in a seat row or a log line:
+ * the body is a non-reversible digest (or, at the ephemeral tier, a socket id
+ * every client already sees), and the prefix that names the tier is dropped
+ * because a roster has no business advertising who is signed in.
+ *
+ * Here rather than in each consumer so the truncation is ONE number. Two apps
+ * each picking their own produce handles that collide at different rates, and
+ * the one that picked too short finds out from a room where two people look
+ * like the same person. `'unknown'` for a malformed id, never a slice of it.
+ */
+export declare function participantHandle(id: string): string;
+//# sourceMappingURL=participantId.d.ts.map

package/dist/participantId.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"participantId.d.ts","sourceRoot":"","sources":["../src/participantId.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAEH,gFAAgF;AAChF,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEnE,6DAA6D;AAC7D,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC;AAEnC,eAAO,MAAM,qBAAqB,EAAE,QAAQ,CAAC,MAAM,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAI7E,CAAC;AAaF;;;GAGG;AACH,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC,mEAAmE;AACnE,eAAO,MAAM,4BAA4B,KAAK,CAAC;AAS/C;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAItE;AAED,6CAA6C;AAC7C,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAG1D;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED,+EAA+E;AAC/E,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAItF;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,OAAO,GAAG,SAAS,IAAI,MAAM,CAEzE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,OAAO,GAAG,SAAS,IAAI,MAAM,CAEzE;AAED,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,OAAO,GAAG,QAAQ,IAAI,MAAM,CAEtE;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC5C,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B,GAAG,iBAAiB,CAKpB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,CAExF;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG3D;AAED,uDAAuD;AACvD,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAE3C;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAGpD"}

package/dist/participantId.js

@@ -0,0 +1,209 @@
+/**
+ * Participant identity — the FORMAT half (pure, isomorphic, zero deps).
+ *
+ * A `ParticipantId` names a *person in a room*, and it is deliberately NOT the
+ * socket id. Until this module existed, `clientId` WAS `socket.id`
+ * (`ws/join.ts`), so every identity in the system died on reconnect and the
+ * codebase carried three separate workarounds for it: the `fk:`/`cid:` name
+ * persistence keys in `rooms/store.ts`, the A/B bucketing that had to abandon
+ * `me.clientId` for a persisted localStorage id (`lib/fragmentDelivery.ts`),
+ * and the leader-takeover heuristics in `ws/join.ts` that exist to recognise a
+ * refreshing presenter whose new socket is a different "client".
+ *
+ * ## The tier is IN the id, on purpose
+ *
+ *   fk:<digest>    account  — derived from the platform ACCOUNT id (the key
+ *                             registry's `userId`, resolved server-side through
+ *                             whoami). Survives reconnects, reloads, restarts,
+ *                             devices, networks — and KEY ROTATION. The `fk`
+ *                             spelling predates that and is kept because
+ *                             consumers parse it; read it as "account".
+ *
+ * ## Derive the account tier from the userId, never from the key
+ *
+ * The X-User-Key is a CREDENTIAL and it rotates. An id hashed from it changes
+ * the moment the key does, and everything keyed on the id — a remembered seat,
+ * a restored name, the same-presenter leader takeover — silently stops
+ * recognising the person. That is the same failure that detached every
+ * tierlist ballot in watchparty (#144), one layer up. `accountId` is the
+ * input; `friendKey` remains accepted ONLY so a consumer that has not yet
+ * resolved userIds keeps working, and loses rotation-stability while it does.
+ *   dev:<digest>   device   — derived from a browser-persisted id. Survives a
+ *                             reload and a reconnect; not a new browser.
+ *   eph:<socketId> ephemeral— anon with no usable storage. Dies with the socket.
+ *
+ * Encoding durability in the id means code that REQUIRES durability can assert
+ * on it (`requireDurable`) instead of hoping. A 45-minute draft seat can demand
+ * `account` or `device`; a demo room can accept `ephemeral`.
+ *
+ * ## `device` is NOT an authorization boundary
+ *
+ * The device id is **client-asserted** — it arrives in the join payload and
+ * nothing proves it. So a `dev:` identity is good enough to carry a display
+ * name or hold a seat among friends, and NOT good enough to gate a capability:
+ * anyone who learns another client's device id can present it. Only the
+ * `account` tier is server-authenticated (the edge resolves the hadoku_session
+ * cookie into X-User-Key; the browser never sees the key). Anything that grants
+ * power — leadership, ownership, a moderation action — must require
+ * `account`. `isAuthenticatedTier` is the check; do not widen it.
+ *
+ * ## Why the id can be logged and put on the wire
+ *
+ * The `fk:` and `dev:` bodies are non-reversible digests, not the source
+ * material (see the server's `deriveParticipantId`, which owns the hashing
+ * because it needs a synchronous crypto primitive this package cannot assume).
+ * The friend key IS the X-User-Key credential, so embedding it raw would hand
+ * every viewer everyone else's key while looking entirely normal on screen —
+ * the same trap `opaqueVoterId` was written to avoid in `tierlist/store.ts`.
+ * Hashing at derivation means there is exactly ONE id per participant rather
+ * than an internal id plus a wire handle to keep in sync.
+ */
+export const PARTICIPANT_ID_PREFIX = {
+    account: 'fk:',
+    device: 'dev:',
+    ephemeral: 'eph:',
+};
+/**
+ * Tier ranking, least → most durable. Derived from one source so the
+ * vocabulary and the ordering cannot drift (the same reason `TIER_RANK` in the
+ * server's `whoami.ts` is a map rather than a list of comparisons).
+ */
+const TIER_RANK = {
+    ephemeral: 0,
+    device: 1,
+    account: 2,
+};
+/**
+ * Shortest friend key we treat as real. Matches the existing `>= 5` checks in
+ * `ws/handlers.ts` and `rooms/store.ts#hasFriendKey` — keep them in step.
+ */
+export const MIN_FRIEND_KEY_LENGTH = 5;
+/**
+ * Shortest device id we accept. Longer than the friend-key floor on purpose:
+ * a friend key is server-injected and known-good, while a device id is
+ * client-asserted, so a short one is far more likely to be junk (or a
+ * collision-farming attempt) than a real persisted id. Clients that can't do
+ * better fall through to `ephemeral`, which is honest rather than broken.
+ */
+export const MIN_DEVICE_ID_LENGTH = 8;
+/** Hex digest length used by the `account` and `device` bodies. */
+export const PARTICIPANT_ID_DIGEST_LENGTH = 16;
+const PARSE_RE = /^(fk|dev|eph):(.+)$/;
+const TIER_BY_SCHEME = {
+    fk: 'account',
+    dev: 'device',
+    eph: 'ephemeral',
+};
+/**
+ * Tier of an id, or `null` if it isn't one. Returns null rather than throwing
+ * or defaulting: an unrecognised id is absence of evidence, and defaulting it
+ * to `ephemeral` would silently admit a malformed id to every path that only
+ * refuses `ephemeral` — the failure would look like a working downgrade.
+ */
+export function participantIdTier(id) {
+    const m = PARSE_RE.exec(id);
+    if (!m)
+        return null;
+    return TIER_BY_SCHEME[m[1]] ?? null;
+}
+/** True for a well-formed id of any tier. */
+export function isParticipantId(id) {
+    return participantIdTier(id) !== null;
+}
+/**
+ * Survives a reconnect (`account` or `device`). This is the check for "may hold
+ * a seat / may have a pending request replayed", NOT for "may do something
+ * privileged" — see `isAuthenticatedTier`.
+ */
+export function isDurableParticipantId(id) {
+    const tier = participantIdTier(id);
+    return tier !== null && TIER_RANK[tier] >= TIER_RANK.device;
+}
+/**
+ * Server-authenticated identity (`account` only). The gate for anything that
+ * grants power. Deliberately narrower than `isDurableParticipantId` because a
+ * device id is client-asserted — see this module's header.
+ */
+export function isAuthenticatedTier(id) {
+    return participantIdTier(id) === 'account';
+}
+/** Rank comparison — `tierAtLeast(id, 'device')` admits device and account. */
+export function participantTierAtLeast(id, minTier) {
+    const tier = participantIdTier(id);
+    if (tier === null)
+        return false;
+    return TIER_RANK[tier] >= TIER_RANK[minTier];
+}
+/**
+ * Whether a friend key is long enough to be treated as real. THE one
+ * definition — it was hand-copied as `length >= 5` across six files, which is
+ * how one of them ends up disagreeing with the rest.
+ *
+ * A type guard, so callers narrow instead of re-asserting with a cast.
+ */
+export function isUsableFriendKey(friendKey) {
+    return typeof friendKey === 'string' && friendKey.length >= MIN_FRIEND_KEY_LENGTH;
+}
+/**
+ * Whether a platform account id (the registry `userId`) is usable. Same floor
+ * as a friend key: it is server-resolved, never client-asserted, so the check
+ * exists only to reject an empty or junk value, not to judge trust.
+ */
+export function isUsableAccountId(accountId) {
+    return typeof accountId === 'string' && accountId.length >= MIN_FRIEND_KEY_LENGTH;
+}
+/** Whether a client-supplied device id is long enough to be treated as real. */
+export function isUsableDeviceId(deviceId) {
+    return typeof deviceId === 'string' && deviceId.length >= MIN_DEVICE_ID_LENGTH;
+}
+/**
+ * Which tier a set of inputs WOULD produce, without needing the hash. Lets the
+ * join path log and gate on the tier before (or without) deriving the id, and
+ * lets tests assert the tier decision independently of the digest.
+ */
+export function resolveParticipantTier(input) {
+    if (isUsableAccountId(input.accountId))
+        return 'account';
+    if (isUsableFriendKey(input.friendKey))
+        return 'account';
+    if (isUsableDeviceId(input.deviceId))
+        return 'device';
+    return 'ephemeral';
+}
+/**
+ * Assemble an id from an already-computed body. The server's
+ * `deriveParticipantId` is the only intended caller for the hashed tiers; it is
+ * exported so both halves share one spelling of the prefixes rather than
+ * concatenating them by hand at each site.
+ */
+export function formatParticipantId(tier, body) {
+    return `${PARTICIPANT_ID_PREFIX[tier]}${body}`;
+}
+/**
+ * The body after the scheme, or `null` for a malformed id. Useful for logs
+ * that want a short handle without the prefix noise; never for reconstructing
+ * the source material, which is not recoverable from a digest.
+ */
+export function participantIdBody(id) {
+    const m = PARSE_RE.exec(id);
+    return m ? m[2] : null;
+}
+/** How much of a participant's body a handle shows. */
+export const PARTICIPANT_HANDLE_LENGTH = 6;
+/**
+ * A short, wire-safe handle for a participant — what you may SHOW a room.
+ *
+ * The one part of an identity that is safe to put in a seat row or a log line:
+ * the body is a non-reversible digest (or, at the ephemeral tier, a socket id
+ * every client already sees), and the prefix that names the tier is dropped
+ * because a roster has no business advertising who is signed in.
+ *
+ * Here rather than in each consumer so the truncation is ONE number. Two apps
+ * each picking their own produce handles that collide at different rates, and
+ * the one that picked too short finds out from a room where two people look
+ * like the same person. `'unknown'` for a malformed id, never a slice of it.
+ */
+export function participantHandle(id) {
+    const body = participantIdBody(id);
+    return body === null ? 'unknown' : body.slice(0, PARTICIPANT_HANDLE_LENGTH);
+}

package/dist/resync.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Reconnect and resync — the CONTRACT, not the transport.
+ *
+ * A client that drops and returns has three problems, and they are separable:
+ * did it miss anything (sequence), is it even talking to the same room
+ * incarnation (epoch), and does the server still agree about who it is
+ * (identity). The rules for all three live here, pure and dependency-free, so
+ * both ends agree on them and either end can test them without a socket.
+ *
+ * **The implementations deliberately stay where they are.** Watchparty's socket
+ * lifecycle is in `apps/ui/src/lib/socket.ts` and is not extracted; a second
+ * consumer whose client is a cross-origin iframe relaying over `postMessage`
+ * has a different transport entirely. What both need to agree on is the RULES,
+ * which is this file.
+ *
+ * ## What watchparty actually stamps today — read this before binding
+ *
+ * `CoreRoomState.lastEventSeq` is incremented **only for playback control
+ * events** (`ws/control.ts`), and it reaches clients in the `snapshot` and
+ * `control_ack` payloads. Chat, presence, health and game envelopes carry no
+ * sequence at all. So `classifySeq` is a rule this package *guarantees*, not a
+ * behaviour watchparty currently exercises end to end — an app that wants gap
+ * detection stamps `SeqCursor` on its own envelopes and runs the classifier.
+ *
+ * That distinction was stated wrongly once (an earlier version of the
+ * extraction reply claimed "every envelope carries seq"), so it is spelled out
+ * here rather than left to be inferred.
+ */
+/**
+ * Where a client is in a room's event stream.
+ *
+ * `epoch` identifies the room INCARNATION. It exists because a sequence number
+ * alone cannot tell "I missed events" from "the server restarted and started
+ * counting again" — and those need opposite responses: catch up versus discard
+ * everything and refetch. Any value works as long as it changes when the room
+ * is rebuilt and not otherwise (a boot id, a restore id, a uuid).
+ */
+export interface SeqCursor {
+    epoch: string;
+    seq: number;
+}
+export type SeqVerdict = 
+/** Exactly the next event. Apply it. */
+'ok'
+/** Already seen. Drop it — do NOT re-apply, and do not resync. */
+ | 'duplicate'
+/** Events were missed. Request a resync. */
+ | 'gap'
+/** Different room incarnation. Discard local state and refetch in full. */
+ | 'epoch-change';
+/**
+ * Classify an incoming event against the last one applied.
+ *
+ * `last === null` means nothing has been applied yet, which is 'ok' rather than
+ * a gap: a client joining mid-stream has missed everything by definition, and
+ * its snapshot — not a resync request — is what establishes the baseline.
+ *
+ * **Sequence numbers are NEVER compared across epochs.** A restarted server
+ * counting from 1 while the client holds 500 would otherwise read as a flood
+ * of duplicates and the client would sit there discarding live events forever.
+ * The epoch check therefore comes first, before any arithmetic.
+ */
+export declare function classifySeq(last: SeqCursor | null, incoming: SeqCursor): SeqVerdict;
+/** How many events a gap skipped. 0 when the verdict is not 'gap'. */
+export declare function missedCount(last: SeqCursor | null, incoming: SeqCursor): number;
+/**
+ * Does this verdict require the client to ask the server for state?
+ *
+ * A helper rather than a comparison at each call site, because the answer is
+ * NOT "anything that isn't ok": a duplicate must not trigger a resync. Under
+ * any retransmit, duplicates arrive in bursts, and resyncing on each one turns
+ * a harmless replay into a request storm against the server that is already
+ * struggling enough to be retransmitting.
+ */
+export declare function needsResync(verdict: SeqVerdict): boolean;
+/** The server's view of us, from the room roster. */
+export interface RosterIdentity {
+    name?: string | null;
+    avatarId?: string | null;
+}
+export interface LocalIdentity {
+    name?: string | null;
+    avatarId?: string | null;
+}
+export interface IdentityReassert {
+    name?: string;
+    avatarId?: string;
+}
+/**
+ * Should the client re-assert its local identity to the server?
+ *
+ * On each snapshot a client compares its own name/avatar against the server's
+ * roster entry FOR ITSELF and emits an identity update only for the fields that
+ * actually disagree, so later snapshots are no-ops.
+ *
+ * **Read `serverEntry` from the ROSTER, not from the snapshot.** Watchparty's
+ * snapshot carries seven fields and has never included a roster; a caller that
+ * looked itself up there got `undefined` permanently, both guards collapsed to
+ * local state alone, and every client with a saved identity re-emitted on
+ * every snapshot — including the room-wide ones. That bug survived a long time
+ * because broken and correct agree on the FIRST snapshot after join and
+ * diverge only afterwards.
+ *
+ * `serverEntry === undefined` still means "assert": that is the genuine
+ * first-snapshot case, where the client cannot know the server's view.
+ *
+ * Known quirk, preserved deliberately: an empty server name does not trigger a
+ * name assert, because an empty string is not a default name under any sane
+ * `isDefaultName`. Widening that is a separate decision with a different blast
+ * radius.
+ *
+ * @param isDefaultName recognises an auto-assigned name; a local name that is
+ *                      still a default is not worth asserting.
+ * @returns the fields to emit, or null when nothing differs.
+ */
+export declare function resolveIdentityReassert(local: LocalIdentity, serverEntry: RosterIdentity | undefined, isDefaultName: (name: string) => boolean): IdentityReassert | null;
+//# sourceMappingURL=resync.d.ts.map

package/dist/resync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resync.d.ts","sourceRoot":"","sources":["../src/resync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,MAAM,UAAU;AACpB,wCAAwC;AACtC,IAAI;AACN,kEAAkE;GAChE,WAAW;AACb,4CAA4C;GAC1C,KAAK;AACP,2EAA2E;GACzE,cAAc,CAAC;AAEnB;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,EAAE,QAAQ,EAAE,SAAS,GAAG,UAAU,CAMnF;AAED,sEAAsE;AACtE,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,EAAE,QAAQ,EAAE,SAAS,GAAG,MAAM,CAG/E;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAExD;AAID,qDAAqD;AACrD,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,aAAa,EACpB,WAAW,EAAE,cAAc,GAAG,SAAS,EACvC,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GACvC,gBAAgB,GAAG,IAAI,CAczB"}