@pithy-sh/core 0.13.0 → 0.14.0

package/src/presence/http/routes.ts

@@ -0,0 +1,165 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { DurableObjectNamespace } from "@cloudflare/workers-types";
+import type { Context, Hono } from "hono";
+import type { PithyHonoEnv } from "../../capability/capability";
+import { remedy } from "../../cli/command";
+import { ForbiddenError, InternalError, NotFoundError, PresenceTicketInvalidError } from "../../error/pithyError";
+import { describeRoute } from "../../http/routeSpec";
+import { requireSameOrigin } from "../../http/sameOrigin";
+import { SUBPROTOCOL_HEADER } from "../../http/subprotocol";
+import { validate } from "../../http/validation";
+import {
+  PRESENCE_ROOMS_BINDING,
+  type PresenceDeclaration,
+  type PresenceRoomKind,
+  participantCap,
+  presenceRoomPath,
+  presenceSocketPath,
+  presenceTicketPath,
+  resolveTicketKeys,
+  sessionParticipantName,
+} from "../declaration";
+import { PRESENCE_ADMISSION_HEADER, type PresenceAdmission } from "../room";
+import { mintPresenceTicket, type PresenceTicketRequest, ticketFromOffer, verifyPresenceTicket } from "../ticket";
+import { requireAuth } from "./guard";
+import { type PresenceRoomDescriptor, PresenceTicket } from "./responses";
+import { PresenceRoomParams, PresenceSessionTicketRequest } from "./schemas";
+
+/**
+ * A capability's presence routes, mounted by `createBackend` under the `basePath` it declared:
+ *
+ *   POST {base}/presence/tickets                   → a ticket for a signed-in user   (bearer | session)
+ *   GET  {base}/presence/rooms/:kind/:recordId     → the room's socket               (a ticket)
+ *
+ * The control-plane door is the seam's own, `POST /control-plane/presence/tickets`, because one management
+ * client reaches every capability's rooms through it; both doors answer the same {@link PresenceTicket}.
+ */
+
+/** Find a declared room kind, or the 404 an undeclared one is. */
+export function roomKind(presence: PresenceDeclaration, kind: string): PresenceRoomKind {
+  const room = presence.rooms.find((candidate) => candidate.kind === kind);
+  if (!room) throw new NotFoundError({ message: "That room kind does not exist.", params: { kind } });
+  return room;
+}
+
+/** Mint the ticket a door answers with. */
+export async function issuePresenceTicket(
+  c: Context<PithyHonoEnv>,
+  presence: PresenceDeclaration,
+  request: PresenceTicketRequest,
+): Promise<PresenceTicket> {
+  const keys = await resolveTicketKeys(presence.ticketKey, c.env as Record<string, unknown>);
+  const { ticket, claims } = await mintPresenceTicket(request, keys);
+  return {
+    ticket,
+    expiresAt: new Date(claims.exp * 1000).toISOString(),
+    kind: claims.kind,
+    recordId: claims.recordId,
+    socketPath: presenceRoomPath(presence.basePath, claims.kind, claims.recordId),
+    protocol: "pithy.presence.v1",
+  };
+}
+
+/** The room kinds a declaration serves, as the manifest reports them. */
+export function describePresenceRooms(presence: PresenceDeclaration): PresenceRoomDescriptor[] {
+  return presence.rooms.map((room) => ({
+    kind: room.kind,
+    scope: room.scope,
+    activities: [...room.activities],
+    maxParticipants: participantCap(room),
+    sessionTicketPath: room.session ? presenceTicketPath(presence.basePath) : null,
+    socketPath: presenceSocketPath(presence.basePath),
+  }));
+}
+
+export function registerPresenceRoutes(app: Hono<PithyHonoEnv>, presence: PresenceDeclaration): void {
+  app.post(
+    presenceTicketPath(presence.basePath),
+    describeRoute({
+      summary: "Mint a presence ticket for the signed-in user.",
+      description:
+        "Admits the caller to one room of a kind this capability declares, when the capability's own read permission admits them to the record. Single use, for 60 seconds. Open the socket at `socketPath`, offering `protocol` and `pithy.ticket.<ticket>` in `Sec-WebSocket-Protocol`.",
+      verification: ["bearer", "session"],
+      responses: { 201: PresenceTicket },
+    }),
+    requireAuth(),
+    requireSameOrigin(),
+    validate("json", PresenceSessionTicketRequest),
+    async (c) => {
+      const body = c.req.valid("json");
+      const room = roomKind(presence, body.kind);
+      const auth = c.var.auth;
+      // `requireAuth` ran; this is the type system catching up.
+      if (!auth) throw new InternalError({ detail: "presence session ticket reached without auth" });
+      const grant = room.session ? await room.session(c, body.recordId) : null;
+      if (!grant) {
+        throw new ForbiddenError({
+          message: "You cannot join that room.",
+          detail: room.session
+            ? `session gate refused ${body.kind}/${body.recordId}`
+            : `${body.kind} admits management clients only`,
+        });
+      }
+      const ticket = await issuePresenceTicket(c, presence, {
+        kind: room.kind,
+        recordId: body.recordId,
+        ref: auth.userId,
+        name: sessionParticipantName(grant.name, auth.userId),
+        origin: "session",
+      });
+      return c.json(ticket satisfies PresenceTicket, 201);
+    },
+  );
+
+  app.get(
+    presenceSocketPath(presence.basePath),
+    describeRoute({
+      summary: "Open a presence room's socket.",
+      description:
+        "Send `Upgrade: websocket` and offer `pithy.presence.v1` and `pithy.ticket.<ticket>` in `Sec-WebSocket-Protocol`; the ticket is the credential, minted by either ticket route for this room. The socket receives who is in the room, then joins, leaves and activity changes as they happen. The frames are in the AsyncAPI contract.",
+      verification: "public",
+      responses: {
+        101: { description: "Switches to a WebSocket. The room pushes presence frames as JSON text." },
+      },
+    }),
+    validate("param", PresenceRoomParams),
+    async (c) => {
+      const { kind, recordId } = c.req.valid("param");
+      const room = roomKind(presence, kind);
+      const ticket = ticketFromOffer(c.req.header(SUBPROTOCOL_HEADER));
+      if (ticket === undefined) throw new PresenceTicketInvalidError({ detail: "no single ticket in the offer" });
+      const keys = await resolveTicketKeys(presence.ticketKey, c.env as Record<string, unknown>);
+      const claims = await verifyPresenceTicket(ticket, { kind, recordId }, keys);
+
+      const admission: PresenceAdmission = {
+        kind,
+        recordId,
+        ref: claims.ref,
+        name: claims.name,
+        origin: claims.origin,
+        ticket: { id: claims.id, exp: claims.exp },
+        activities: [...room.activities],
+        maxParticipants: participantCap(room),
+      };
+      // A fresh request, so the admission header is ours whatever the client sent under that name.
+      const request = new Request(c.req.url, c.req.raw);
+      request.headers.set(PRESENCE_ADMISSION_HEADER, JSON.stringify(admission));
+      return roomStub(c, kind, recordId).fetch(request);
+    },
+  );
+}
+
+/** The one room for this record. */
+function roomStub(c: Context<PithyHonoEnv>, kind: string, recordId: string) {
+  const ns = (c.env as Record<string, unknown>)[PRESENCE_ROOMS_BINDING] as DurableObjectNamespace | undefined;
+  if (!ns) {
+    throw new InternalError({
+      message: "Presence is not available right now.",
+      action: `Bind the ${PRESENCE_ROOMS_BINDING} Durable Object. ${remedy("upgrade", {}, { runtime: true }).say((command) => `${command} writes it.`)}`,
+      detail: `no ${PRESENCE_ROOMS_BINDING} binding`,
+    });
+  }
+  return ns.get(ns.idFromName(`${kind}:${recordId}`)) as unknown as { fetch(request: Request): Promise<Response> };
+}

package/src/presence/http/schemas.ts

@@ -0,0 +1,39 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { PresenceParticipantName, PresenceParticipantRef } from "../frames";
+import { PresenceRecordId, PresenceRoomKindName } from "../names";
+
+/** The room a ticket is for. */
+const room = {
+  kind: PresenceRoomKindName.describe("The room kind, as the manifest lists it — `support.thread`."),
+  recordId: PresenceRecordId.describe("The record the room is about."),
+};
+
+/** `POST {base}/presence/tickets` — a signed-in user asks to join a room. The participant is that user. */
+export const PresenceSessionTicketRequest = z
+  .object(room)
+  .describe("The room a signed-in user asks a presence ticket for. The participant is the caller.");
+export type PresenceSessionTicketRequest = z.infer<typeof PresenceSessionTicketRequest>;
+
+/**
+ * `POST /control-plane/presence/tickets` — a management client asks to join a room, naming its participant.
+ * The body is signed with the call, which is what makes the participant the client's own claim.
+ */
+export const ControlPlanePresenceTicketRequest = z
+  .object({
+    ...room,
+    participant: z
+      .object({
+        ref: PresenceParticipantRef,
+        name: PresenceParticipantName,
+      })
+      .describe("Who joins: the client's own opaque reference for them, and the name the others see."),
+  })
+  .describe("The room a management client asks a presence ticket for, and who joins it.");
+export type ControlPlanePresenceTicketRequest = z.infer<typeof ControlPlanePresenceTicketRequest>;
+
+/** The socket route's path parameters. */
+export const PresenceRoomParams = z.object(room).describe("The room a presence socket joins: its kind and its record.");
+export type PresenceRoomParams = z.infer<typeof PresenceRoomParams>;

package/src/presence/names.ts

@@ -0,0 +1,45 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+
+/**
+ * The three names a presence room is made of, as Zod schemas and nothing else.
+ *
+ * A leaf on purpose: the manifest's room descriptor, the ticket responses and the frames all read these, and
+ * a management client holds those in a browser. So this module imports zod and no other thing — never the
+ * declaration, which names the Hono context a session gate runs in.
+ */
+
+/** A room kind's name: the declaring capability's name, a dot, and a noun — `support.thread`. */
+export const PresenceRoomKindName = z
+  .string()
+  .regex(
+    /^[a-z][a-z0-9]*(?:\.[a-z][a-z0-9_]*)+$/,
+    "A room kind is the capability's name, a dot, and a lowercase noun — `support.thread`.",
+  )
+  .max(64)
+  .describe(
+    "A room kind: the declaring capability's name, a dot, and a noun — `support.thread`. The first segment is always the capability that declares it, so two capabilities cannot declare the same kind.",
+  );
+export type PresenceRoomKindName = z.infer<typeof PresenceRoomKindName>;
+
+/** One activity a participant may announce — `viewing`, `replying`. A closed vocabulary per room kind, never free text. */
+export const PresenceActivity = z
+  .string()
+  .regex(/^[a-z][a-z0-9_]*$/, "An activity is one lowercase word — `viewing`, `replying`.")
+  .max(32)
+  .describe("What a participant is doing in the room — one of the values its room kind declares, never free text.");
+export type PresenceActivity = z.infer<typeof PresenceActivity>;
+
+/**
+ * The record a room is about — the id the declaring capability's own routes take. Constrained to what fits a
+ * path segment and a Durable Object name without escaping.
+ */
+export const PresenceRecordId = z
+  .string()
+  .min(1)
+  .max(128)
+  .regex(/^[A-Za-z0-9._:-]+$/, "A record id is letters, digits, `.`, `_`, `:` and `-`.")
+  .describe("The record the room is about — the id the declaring capability's own routes use for it.");
+export type PresenceRecordId = z.infer<typeof PresenceRecordId>;

package/src/presence/room.ts

@@ -0,0 +1,145 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { PresenceOrigin, PresenceParticipant, PresenceParticipantName, PresenceParticipantRef } from "./frames";
+import { PresenceActivity, PresenceRecordId, PresenceRoomKindName } from "./names";
+
+/**
+ * **What a room knows, and where it keeps it: on its sockets, and nowhere else.**
+ *
+ * A room is one Durable Object on the Hibernation API. When it hibernates its memory goes, so everything it
+ * must still know when it wakes rides in each socket's attachment, read back from `getWebSockets()`: the
+ * participant, the version the socket negotiated, the room kind's rules, and which tickets have been spent.
+ * Nothing is written to D1, KV or Durable Object storage. When the last socket closes, the room is gone.
+ *
+ * This module is the logic of that, pure, so it is tested without a runtime; `./durableObject.ts` is the
+ * thin part that reads and writes attachments.
+ */
+
+/** A spent ticket: its id, and when it would have expired anyway — after which remembering it is pointless. */
+export const SpentTicket = z
+  .object({
+    id: z.string().uuid().describe("The spent ticket's id."),
+    exp: z.number().int().describe("When the ticket would have expired, in seconds since the epoch."),
+  })
+  .describe("A ticket a room has redeemed, kept until it would have expired.");
+export type SpentTicket = z.infer<typeof SpentTicket>;
+
+/**
+ * What the Worker's socket route tells the room, on a header only the Worker can set: a verified ticket's
+ * participant, the ticket itself, and the room kind's rules. The room trusts this and nothing a client sent.
+ */
+export const PresenceAdmission = z
+  .object({
+    kind: PresenceRoomKindName.describe("The room kind."),
+    recordId: PresenceRecordId.describe("The record the room is about."),
+    ref: PresenceParticipantRef,
+    name: PresenceParticipantName,
+    origin: PresenceOrigin,
+    ticket: SpentTicket.describe("The ticket this socket is redeeming."),
+    activities: z
+      .array(PresenceActivity)
+      .min(1)
+      .describe("The room kind's declared activities. The first is what a participant starts as."),
+    maxParticipants: z.number().int().positive().describe("The room kind's participant cap."),
+  })
+  .describe("A verified admission, forwarded from the Worker's socket route to the room.");
+export type PresenceAdmission = z.infer<typeof PresenceAdmission>;
+
+/** The server-set header carrying a {@link PresenceAdmission} into the room. */
+export const PRESENCE_ADMISSION_HEADER = "x-pithy-presence-admission";
+
+/** What one socket carries through hibernation. Kept far under the 16,384-byte attachment ceiling. */
+export const PresenceAttachment = z
+  .object({
+    participant: PresenceParticipant.describe("Who this socket is, and what they are doing."),
+    version: z.string().describe("The negotiated subprotocol."),
+    ticket: SpentTicket.describe("The ticket this socket redeemed."),
+    activities: z.array(PresenceActivity).min(1).describe("The room kind's declared activities."),
+    spent: z
+      .array(SpentTicket)
+      .describe("Tickets redeemed by sockets that have since closed, carried so a hibernated room still refuses them."),
+  })
+  .describe("The participant and room state a presence socket keeps across hibernation.");
+export type PresenceAttachment = z.infer<typeof PresenceAttachment>;
+
+/** Every ticket a room still remembers as spent, from its sockets' attachments and its own memory. */
+export function spentTickets(
+  attachments: readonly PresenceAttachment[],
+  remembered: readonly SpentTicket[],
+  nowSeconds: number,
+): Set<string> {
+  const spent = new Set<string>();
+  const add = (ticket: SpentTicket) => {
+    if (ticket.exp > nowSeconds) spent.add(ticket.id);
+  };
+  for (const attachment of attachments) {
+    add(attachment.ticket);
+    for (const ticket of attachment.spent) add(ticket);
+  }
+  for (const ticket of remembered) add(ticket);
+  return spent;
+}
+
+/** Why a room refuses an admission, or `null` to admit. */
+export type AdmissionRefusal = "spent" | "full" | null;
+
+/** Decide one admission against the room as it stands. */
+export function admit(
+  admission: PresenceAdmission,
+  attachments: readonly PresenceAttachment[],
+  remembered: readonly SpentTicket[],
+  nowSeconds: number,
+): AdmissionRefusal {
+  if (spentTickets(attachments, remembered, nowSeconds).has(admission.ticket.id)) return "spent";
+  if (attachments.length >= admission.maxParticipants) return "full";
+  return null;
+}
+
+/**
+ * The most spent tickets one attachment carries. A ticket is honored for 60 seconds, so this is how many
+ * sockets a room may see redeemed and closed within a minute before it starts forgetting the soonest to
+ * expire; at about 60 bytes each it keeps an attachment far under its 16,384-byte ceiling.
+ */
+export const MAX_CARRIED_SPENT = 160;
+
+/** Unexpired, once each, never `own`, and at most {@link MAX_CARRIED_SPENT} — the latest to expire kept. */
+function liveSpent(tickets: readonly SpentTicket[], own: string, nowSeconds: number): SpentTicket[] {
+  const byId = new Map<string, SpentTicket>();
+  for (const ticket of tickets) {
+    if (ticket.exp > nowSeconds && ticket.id !== own) byId.set(ticket.id, ticket);
+  }
+  const live = [...byId.values()];
+  return live.length > MAX_CARRIED_SPENT ? live.sort((a, b) => b.exp - a.exp).slice(0, MAX_CARRIED_SPENT) : live;
+}
+
+/**
+ * The spent list a socket joining a room starts with: what the room remembers in memory, moved onto the
+ * socket, where it survives hibernation. A room's memory is only for the tickets of sockets that closed with
+ * no other socket left to carry them; the moment a socket is there again, it carries them.
+ */
+export function inheritSpent(remembered: readonly SpentTicket[], own: string, nowSeconds: number): SpentTicket[] {
+  return liveSpent(remembered, own, nowSeconds);
+}
+
+/**
+ * The spent list a surviving socket carries once another closes: its own, plus the closing socket's ticket
+ * and everything it carried, less what has expired. Returns `null` when nothing changed, so a room writes no
+ * attachment it does not need to.
+ */
+export function carrySpent(
+  survivor: PresenceAttachment,
+  closing: PresenceAttachment,
+  nowSeconds: number,
+): SpentTicket[] | null {
+  const next = liveSpent([...survivor.spent, closing.ticket, ...closing.spent], survivor.ticket.id, nowSeconds);
+  const same =
+    next.length === survivor.spent.length && next.every((ticket, index) => survivor.spent[index]?.id === ticket.id);
+  return same ? null : next;
+}
+
+/** Whether a client may announce this activity in this room. */
+export function declaresActivity(attachment: PresenceAttachment, activity: string): boolean {
+  return attachment.activities.includes(activity);
+}

package/src/presence/ticket.ts

@@ -0,0 +1,145 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { base64UrlDecode, base64UrlEncode } from "../controlPlane/token/base64url";
+import { PresenceTicketInvalidError } from "../error/pithyError";
+import { PRESENCE_TICKET_TTL_SECONDS } from "./declaration";
+import { PresenceOrigin, PresenceParticipantName, PresenceParticipantRef } from "./frames";
+import { PresenceRecordId, PresenceRoomKindName } from "./names";
+
+/**
+ * **A presence ticket: single use, 60 seconds, one room, one participant.**
+ *
+ * `<claims>.<signature>`, both unpadded base64url, the signature an HMAC-SHA256 over the claims segment with
+ * the Worker's `presence-ticket-key` secret. The alphabet and the dot are all token characters, so a
+ * ticket rides in `Sec-WebSocket-Protocol` as `pithy.ticket.<ticket>` untouched.
+ *
+ * What a ticket proves is that **this Worker** minted it, behind a gate, for these claims. Verifying it
+ * here checks the signature, the expiry and the room; spending it is the room's job, because only the room
+ * the ticket names can redeem it, which is what makes "single use" decidable without a write anywhere.
+ *
+ * Every failure is the one {@link PresenceTicketInvalidError}, with the step in `detail` for the log: a caller
+ * holding someone else's ticket learns that it does not work, never why.
+ */
+
+/** The subprotocol prefix a ticket travels under, beside `pithy.presence.v1`. */
+export const PRESENCE_TICKET_PROTOCOL_PREFIX = "pithy.ticket.";
+
+/** What a ticket says, signed. */
+export const PresenceTicketClaims = z
+  .object({
+    v: z.literal(1).describe("The ticket format. A different one is refused."),
+    id: z.string().uuid().describe("The ticket's own id — what the room records as spent."),
+    kind: PresenceRoomKindName.describe("The room kind the ticket admits to."),
+    recordId: PresenceRecordId.describe("The record the room is about."),
+    ref: PresenceParticipantRef.describe(
+      "Who the participant is: the client's opaque ref, or the signed-in user's id.",
+    ),
+    name: PresenceParticipantName.describe("How other participants see them."),
+    origin: PresenceOrigin.describe("Which door the ticket was minted at."),
+    exp: z.number().int().positive().describe("When the ticket stops being honored, in seconds since the epoch."),
+  })
+  .describe("The claims a presence ticket carries, signed by the Worker that minted it.");
+export type PresenceTicketClaims = z.infer<typeof PresenceTicketClaims>;
+
+/** What a caller asks a ticket for: everything but the id and the expiry, which the minter decides. */
+export type PresenceTicketRequest = Omit<PresenceTicketClaims, "v" | "id" | "exp">;
+
+const encoder = new TextEncoder();
+
+async function hmacKey(secret: string): Promise<CryptoKey> {
+  return crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, [
+    "sign",
+    "verify",
+  ]);
+}
+
+/** Mint a ticket. `keys[0]` signs. */
+export async function mintPresenceTicket(
+  request: PresenceTicketRequest,
+  keys: readonly string[],
+  now: Date = new Date(),
+): Promise<{ ticket: string; claims: PresenceTicketClaims }> {
+  const [signing] = keys;
+  if (signing === undefined) throw new PresenceTicketInvalidError({ detail: "no signing key" });
+  const claims = PresenceTicketClaims.parse({
+    v: 1,
+    id: crypto.randomUUID(),
+    ...request,
+    exp: Math.floor(now.getTime() / 1000) + PRESENCE_TICKET_TTL_SECONDS,
+  });
+  const body = base64UrlEncode(encoder.encode(JSON.stringify(claims)));
+  const signature = new Uint8Array(await crypto.subtle.sign("HMAC", await hmacKey(signing), encoder.encode(body)));
+  return { ticket: `${body}.${base64UrlEncode(signature)}`, claims };
+}
+
+/** Decode a segment, mapping the control-plane decoder's refusal onto this one. */
+function decode(segment: string, what: string): Uint8Array {
+  try {
+    return base64UrlDecode(segment);
+  } catch (cause) {
+    throw new PresenceTicketInvalidError({ detail: `${what} is not base64url` }, { cause });
+  }
+}
+
+/**
+ * Verify a ticket for one room: the signature under any honored key, the expiry, and that it names this
+ * kind and this record. Returns the claims; spending them is the room's.
+ */
+export async function verifyPresenceTicket(
+  ticket: string,
+  room: { kind: string; recordId: string },
+  keys: readonly string[],
+  now: Date = new Date(),
+): Promise<PresenceTicketClaims> {
+  const parts = ticket.split(".");
+  const [body, signature] = parts;
+  if (parts.length !== 2 || !body || !signature) throw new PresenceTicketInvalidError({ detail: "not two segments" });
+  const signed = decode(signature, "signature");
+  let authentic = false;
+  for (const key of keys) {
+    if (await crypto.subtle.verify("HMAC", await hmacKey(key), signed, encoder.encode(body))) {
+      authentic = true;
+      break;
+    }
+  }
+  if (!authentic) throw new PresenceTicketInvalidError({ detail: "signature does not verify under any honored key" });
+
+  let json: unknown;
+  try {
+    json = JSON.parse(new TextDecoder().decode(decode(body, "claims")));
+  } catch (cause) {
+    if (cause instanceof PresenceTicketInvalidError) throw cause;
+    throw new PresenceTicketInvalidError({ detail: "claims are not JSON" }, { cause });
+  }
+  const parsed = PresenceTicketClaims.safeParse(json);
+  if (!parsed.success) throw new PresenceTicketInvalidError({ detail: "claims do not parse" });
+  const claims = parsed.data;
+
+  const seconds = Math.floor(now.getTime() / 1000);
+  if (claims.exp <= seconds) throw new PresenceTicketInvalidError({ detail: `expired at ${claims.exp}` });
+  // A ticket living past its stated life was not minted here, whatever signed it.
+  if (claims.exp > seconds + PRESENCE_TICKET_TTL_SECONDS) {
+    throw new PresenceTicketInvalidError({ detail: `expiry ${claims.exp} is beyond the ticket lifetime` });
+  }
+  if (claims.kind !== room.kind || claims.recordId !== room.recordId) {
+    throw new PresenceTicketInvalidError({
+      detail: `minted for ${claims.kind}/${claims.recordId}, presented at ${room.kind}/${room.recordId}`,
+    });
+  }
+  return claims;
+}
+
+/**
+ * The ticket from a subprotocol offer, or `undefined` when none rides in it. More than one is refused as
+ * none: an offer is one client's, and two tickets in it is not something a client means.
+ */
+export function ticketFromOffer(offered: string | null | undefined): string | undefined {
+  const tickets = (offered ?? "")
+    .split(",")
+    .map((protocol) => protocol.trim())
+    .filter((protocol) => protocol.startsWith(PRESENCE_TICKET_PROTOCOL_PREFIX))
+    .map((protocol) => protocol.slice(PRESENCE_TICKET_PROTOCOL_PREFIX.length));
+  return tickets.length === 1 ? tickets[0] : undefined;
+}