@pithy-sh/core 0.13.0 → 0.14.0

package/dist/presence/declaration.d.ts

@@ -0,0 +1,154 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { Context } from "hono";
+import type { BindingSpecInput } from "../capability/bindings";
+import type { PithyHonoEnv } from "../capability/capability";
+/**
+ * **Presence rooms: who else has a record open, live, from the adopter's own Worker.**
+ *
+ * A capability declares the room kinds it serves beside its admin routes, on {@link Capability.presence}: a
+ * name (`support.thread`), the control-plane scope that reads the record (`support:threads:read`), and the
+ * activities a participant may announce (`viewing`, `replying`). A room is one kind plus one record id, and
+ * it lives in one hibernating Durable Object, `PresenceRoom`, that holds nothing but who is in it.
+ *
+ * Joining takes a **ticket**, because a browser's `WebSocket` sets no headers and so cannot carry either the
+ * control-plane token or, cross-origin, a session cookie. A ticket is minted by one of two routes — the
+ * control-plane one behind the kind's scope, or the capability's own session one behind its own read
+ * permission — and presented once, in the subprotocol offer, within 60 seconds.
+ *
+ * **Presence adds no scope of its own.** Anyone who may read a record may see who else has it open, so the
+ * room kind names the scope that already reads the record and the session gate the capability already has.
+ *
+ * This module is pure: zod, types and constants. The routes are in `./http/routes.ts`, the Durable Object in
+ * `./durableObject.ts`, and nothing here imports either.
+ */
+/** The Durable Object binding every room lives behind. One namespace for every room kind in a Worker. */
+export declare const PRESENCE_ROOMS_BINDING = "PRESENCE_ROOMS";
+/** The class that backs {@link PRESENCE_ROOMS_BINDING}, and the module the Worker's entry re-exports it from. */
+export declare const PRESENCE_ROOM_CLASS = "PresenceRoom";
+/** Its own module, never a package entry point, so `pithy.config.ts` can load the capability in Node. */
+export declare const PRESENCE_ROOM_MODULE = "@pithy-sh/core/src/presence/durableObject";
+/**
+ * The binding a capability that declares room kinds requires. `defineCapability` adds it, so a capability
+ * never spells it; a kit capability's `pithy.manifest.json` names it exactly as written here, which is what
+ * `pithy add` and `pithy upgrade` wire through the Durable Object path (#428).
+ */
+export declare const PRESENCE_ROOMS_BINDING_SPEC: BindingSpecInput;
+/**
+ * The secret tickets are signed with: one per Worker environment, generated, never typed. A capability that
+ * declares room kinds declares this name in its `@pithy-sh/secrets` registry with {@link
+ * PRESENCE_TICKET_KEY_ENTRY} and reads it through `secretsStore`, and its manifest lists it under
+ * `devSecrets` so `pithy add` mints the local value. The name is the join key, so every capability that
+ * declares rooms in one Worker signs and verifies with the one key.
+ */
+export declare const PRESENCE_TICKET_KEY_SECRET = "presence-ticket-key";
+/**
+ * The registry entry for {@link PRESENCE_TICKET_KEY_SECRET}, in the shape `defineSecretRegistry` takes. Its
+ * value is arbitrary — nothing outside the Worker has to agree with it — so it is `devValue: "random"`, and
+ * rotatable because {@link PresenceTicketKey} accepts every version still honored.
+ */
+export declare const PRESENCE_TICKET_KEY_ENTRY: {
+    readonly backend: "d1";
+    readonly scope: "environment";
+    readonly rotatable: true;
+    readonly valueType: "text";
+    readonly devValue: "random";
+};
+/** How long a minted ticket is honored, in seconds. Long enough to open a socket, short enough to be useless later. */
+export declare const PRESENCE_TICKET_TTL_SECONDS = 60;
+/** The participant cap a room kind gets when it declares none. */
+export declare const DEFAULT_PRESENCE_PARTICIPANTS = 25;
+/** The most participants any room kind may declare. A room is one Durable Object, and every frame fans out to all of them. */
+export declare const MAX_PRESENCE_PARTICIPANTS = 100;
+/** The largest frame a room accepts from a client, in bytes. The one frame a client sends is an activity name. */
+export declare const PRESENCE_MAX_FRAME_BYTES = 1024;
+/** The most activities one room kind may declare. */
+export declare const MAX_PRESENCE_ACTIVITIES = 16;
+/** What the session gate grants: the participant's display name, or the user id when it names none. */
+export interface PresenceSessionGrant {
+    /**
+     * How other participants see this user. Trimmed and cut to 80 characters; the user id when it is missing
+     * or blank, so a gate can pass a stored display name through as it is.
+     */
+    readonly name?: string;
+}
+/**
+ * The name a session participant joins under: the gate's, trimmed and cut to fit, or the user id when the
+ * gate names none or a blank one. Always a name a ticket accepts — a display name is the user's own data, and
+ * one too long or empty must not lock them out of every room.
+ */
+export declare function sessionParticipantName(name: string | undefined, userId: string): string;
+/**
+ * The capability's own permission for reading one record, for a signed-in user of the app. Answer a grant
+ * to admit, `null` to refuse. `c.var.auth` is already set when it runs; it is the capability's job to say
+ * whether that user may read `recordId`, exactly as its own read route would.
+ */
+export type PresenceSessionGate = (c: Context<PithyHonoEnv>, recordId: string) => PresenceSessionGrant | null | Promise<PresenceSessionGrant | null>;
+/** One room kind a capability serves. */
+export interface PresenceRoomKind {
+    /** The kind's name — `support.thread`. Its first segment must be the declaring capability's name. */
+    readonly kind: string;
+    /** The control-plane scope that reads the record. A management client joins with exactly this scope. */
+    readonly scope: string;
+    /** The activities a participant may announce. The first is what a participant starts as. */
+    readonly activities: readonly [string, ...string[]];
+    /** The participant cap. Defaults to {@link DEFAULT_PRESENCE_PARTICIPANTS}, at most {@link MAX_PRESENCE_PARTICIPANTS}. */
+    readonly maxParticipants?: number;
+    /**
+     * Who of the app's own signed-in users may join: the capability's read permission for the record. Absent,
+     * the kind admits management clients only and the session ticket route refuses it.
+     */
+    readonly session?: PresenceSessionGate;
+}
+/**
+ * The secret tickets are signed with: the value, every value still honored during a rotation (the first
+ * signs), or a resolver reading it from the Worker env per request — which is the only form a secret read
+ * through `@pithy-sh/secrets` can take, since `env` exists only per request.
+ */
+export type PresenceTicketKey = string | readonly string[] | ((env: Record<string, unknown>) => string | readonly string[] | Promise<string | readonly string[]>);
+/** A capability's presence declaration — see {@link Capability.presence}. */
+export interface PresenceDeclaration {
+    /**
+     * Where this capability mounts its presence routes: `{basePath}/presence/tickets` and
+     * `{basePath}/presence/rooms/:kind/:recordId`. The capability's own resolved `basePath`, never its default.
+     */
+    readonly basePath: string;
+    /** The room kinds it serves. */
+    readonly rooms: readonly PresenceRoomKind[];
+    /** The ticket signing key — {@link PRESENCE_TICKET_KEY_SECRET}, read through the capability's own secrets reader. */
+    readonly ticketKey: PresenceTicketKey;
+}
+/** The session ticket route, under a capability's base path. */
+export declare function presenceTicketPath(basePath: string): string;
+/** The socket route, under a capability's base path, as Hono registers it. */
+export declare function presenceSocketPath(basePath: string): string;
+/** The socket path for one room, ready to open. */
+export declare function presenceRoomPath(basePath: string, kind: string, recordId: string): string;
+/** The participant cap a room kind runs with. */
+export declare function participantCap(room: PresenceRoomKind): number;
+/** One of the capability's own admin routes, as far as the scope rule reads it: its method and the scope it requires. */
+export interface PresenceGatingRoute {
+    method: string;
+    scope: string | null;
+}
+/**
+ * Refuse a declaration no room could be served from, where it is written and naming the capability: a kind
+ * outside the capability's own name, a duplicate, a scope that is not one, an activity that is not one, a
+ * cap out of range. A declaration that reached a request would be refused there, by a caller, in a way only
+ * the operator can fix.
+ *
+ * **A room kind's scope is one the capability's own admin routes already require, and only `GET`s require
+ * it** — compared against `adminRoutes`, the same artifact `capabilityHealthSources` polices health keys
+ * with, and for the same reason. `pithy dashboard connect` offers the scopes it reads off `adminRoutes`, so
+ * a scope no route requires — one of presence's own, a near-miss, another capability's — is never offered
+ * and never in the default grant, and the room is unjoinable from every management client with no error to
+ * say why. And a scope that also gates a write would make joining a room need a mutation grant, which
+ * inverts the read rule `grant.ts` applies.
+ */
+export declare function assertPresenceDeclaration(capability: string, presence: PresenceDeclaration, adminRoutes: readonly PresenceGatingRoute[]): void;
+/**
+ * The ticket signing keys, resolved and non-empty — the first signs, every one verifies. A blank entry is
+ * dropped rather than tried, since WebCrypto refuses a zero-length key with an error that names nothing.
+ */
+export declare function resolveTicketKeys(key: PresenceTicketKey, env: Record<string, unknown>): Promise<string[]>;
+//# sourceMappingURL=declaration.d.ts.map

package/dist/presence/declaration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"declaration.d.ts","sourceRoot":"","sources":["../../src/presence/declaration.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAO7D;;;;;;;;;;;;;;;;;;GAkBG;AAEH,yGAAyG;AACzG,eAAO,MAAM,sBAAsB,mBAAmB,CAAC;AAEvD,iHAAiH;AACjH,eAAO,MAAM,mBAAmB,iBAAiB,CAAC;AAElD,yGAAyG;AACzG,eAAO,MAAM,oBAAoB,8CAA8C,CAAC;AAEhF;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,EAAE,gBAKzC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,wBAAwB,CAAC;AAEhE;;;;GAIG;AACH,eAAO,MAAM,yBAAyB;aACpC,OAAO,EAAE,IAAI;aACb,KAAK,EAAE,aAAa;aACpB,SAAS;aACT,SAAS,EAAE,MAAM;aACjB,QAAQ,EAAE,QAAQ;CACV,CAAC;AAEX,uHAAuH;AACvH,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C,kEAAkE;AAClE,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAEhD,8HAA8H;AAC9H,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAE7C,kHAAkH;AAClH,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAE7C,qDAAqD;AACrD,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C,uGAAuG;AACvG,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEvF;AAYD;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAChC,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,EACxB,QAAQ,EAAE,MAAM,KACb,oBAAoB,GAAG,IAAI,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC;AAExE,yCAAyC;AACzC,MAAM,WAAW,gBAAgB;IAC/B,qGAAqG;IACrG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wGAAwG;IACxG,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,4FAA4F;IAC5F,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;IACpD,yHAAyH;IACzH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,mBAAmB,CAAC;CACxC;AAED;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GACzB,MAAM,GACN,SAAS,MAAM,EAAE,GACjB,CAAC,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;AAEzG,6EAA6E;AAC7E,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,gCAAgC;IAChC,QAAQ,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC5C,qHAAqH;IACrH,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;CACvC;AAED,gEAAgE;AAChE,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,8EAA8E;AAC9E,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,mDAAmD;AACnD,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEzF;AAED,iDAAiD;AACjD,wBAAgB,cAAc,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAE7D;AAED,yHAAyH;AACzH,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,mBAAmB,EAC7B,WAAW,EAAE,SAAS,mBAAmB,EAAE,GAC1C,IAAI,CAqDN;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,iBAAiB,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAW/G"}

package/dist/presence/declaration.js

@@ -0,0 +1,164 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { InternalError } from "../error/pithyError.js";
+import { remedy } from "../cli/command.js";
+import { ControlPlaneScope } from "../controlPlane/scope/scope.js";
+import { PresenceActivity, PresenceRoomKindName } from "./names.js";
+import "./frames.js";
+//#region src/presence/declaration.ts
+/**
+* **Presence rooms: who else has a record open, live, from the adopter's own Worker.**
+*
+* A capability declares the room kinds it serves beside its admin routes, on {@link Capability.presence}: a
+* name (`support.thread`), the control-plane scope that reads the record (`support:threads:read`), and the
+* activities a participant may announce (`viewing`, `replying`). A room is one kind plus one record id, and
+* it lives in one hibernating Durable Object, `PresenceRoom`, that holds nothing but who is in it.
+*
+* Joining takes a **ticket**, because a browser's `WebSocket` sets no headers and so cannot carry either the
+* control-plane token or, cross-origin, a session cookie. A ticket is minted by one of two routes — the
+* control-plane one behind the kind's scope, or the capability's own session one behind its own read
+* permission — and presented once, in the subprotocol offer, within 60 seconds.
+*
+* **Presence adds no scope of its own.** Anyone who may read a record may see who else has it open, so the
+* room kind names the scope that already reads the record and the session gate the capability already has.
+*
+* This module is pure: zod, types and constants. The routes are in `./http/routes.ts`, the Durable Object in
+* `./durableObject.ts`, and nothing here imports either.
+*/
+/** The Durable Object binding every room lives behind. One namespace for every room kind in a Worker. */
+const PRESENCE_ROOMS_BINDING = "PRESENCE_ROOMS";
+/** The class that backs {@link PRESENCE_ROOMS_BINDING}, and the module the Worker's entry re-exports it from. */
+const PRESENCE_ROOM_CLASS = "PresenceRoom";
+/** Its own module, never a package entry point, so `pithy.config.ts` can load the capability in Node. */
+const PRESENCE_ROOM_MODULE = "@pithy-sh/core/src/presence/durableObject";
+/**
+* The binding a capability that declares room kinds requires. `defineCapability` adds it, so a capability
+* never spells it; a kit capability's `pithy.manifest.json` names it exactly as written here, which is what
+* `pithy add` and `pithy upgrade` wire through the Durable Object path (#428).
+*/
+const PRESENCE_ROOMS_BINDING_SPEC = {
+	type: "durable_object",
+	name: PRESENCE_ROOMS_BINDING,
+	className: PRESENCE_ROOM_CLASS,
+	classModule: PRESENCE_ROOM_MODULE
+};
+/**
+* The secret tickets are signed with: one per Worker environment, generated, never typed. A capability that
+* declares room kinds declares this name in its `@pithy-sh/secrets` registry with {@link
+* PRESENCE_TICKET_KEY_ENTRY} and reads it through `secretsStore`, and its manifest lists it under
+* `devSecrets` so `pithy add` mints the local value. The name is the join key, so every capability that
+* declares rooms in one Worker signs and verifies with the one key.
+*/
+const PRESENCE_TICKET_KEY_SECRET = "presence-ticket-key";
+/**
+* The registry entry for {@link PRESENCE_TICKET_KEY_SECRET}, in the shape `defineSecretRegistry` takes. Its
+* value is arbitrary — nothing outside the Worker has to agree with it — so it is `devValue: "random"`, and
+* rotatable because {@link PresenceTicketKey} accepts every version still honored.
+*/
+const PRESENCE_TICKET_KEY_ENTRY = {
+	backend: "d1",
+	scope: "environment",
+	rotatable: true,
+	valueType: "text",
+	devValue: "random"
+};
+/** How long a minted ticket is honored, in seconds. Long enough to open a socket, short enough to be useless later. */
+const PRESENCE_TICKET_TTL_SECONDS = 60;
+/** The participant cap a room kind gets when it declares none. */
+const DEFAULT_PRESENCE_PARTICIPANTS = 25;
+/** The most participants any room kind may declare. A room is one Durable Object, and every frame fans out to all of them. */
+const MAX_PRESENCE_PARTICIPANTS = 100;
+/** The largest frame a room accepts from a client, in bytes. The one frame a client sends is an activity name. */
+const PRESENCE_MAX_FRAME_BYTES = 1024;
+/** The most activities one room kind may declare. */
+const MAX_PRESENCE_ACTIVITIES = 16;
+/**
+* The name a session participant joins under: the gate's, trimmed and cut to fit, or the user id when the
+* gate names none or a blank one. Always a name a ticket accepts — a display name is the user's own data, and
+* one too long or empty must not lock them out of every room.
+*/
+function sessionParticipantName(name, userId) {
+	return fitName(name ?? "") || fitName(userId) || "Participant";
+}
+/** Trim, then cut to {@link PRESENCE_PARTICIPANT_NAME_MAX} code units without splitting a character. */
+function fitName(raw) {
+	let fitted = "";
+	for (const char of raw.trim()) {
+		if (fitted.length + char.length > 80) break;
+		fitted += char;
+	}
+	return fitted.trim();
+}
+/** The session ticket route, under a capability's base path. */
+function presenceTicketPath(basePath) {
+	return `${basePath}/presence/tickets`;
+}
+/** The socket route, under a capability's base path, as Hono registers it. */
+function presenceSocketPath(basePath) {
+	return `${basePath}/presence/rooms/:kind/:recordId`;
+}
+/** The socket path for one room, ready to open. */
+function presenceRoomPath(basePath, kind, recordId) {
+	return `${basePath}/presence/rooms/${encodeURIComponent(kind)}/${encodeURIComponent(recordId)}`;
+}
+/** The participant cap a room kind runs with. */
+function participantCap(room) {
+	return room.maxParticipants ?? 25;
+}
+/**
+* Refuse a declaration no room could be served from, where it is written and naming the capability: a kind
+* outside the capability's own name, a duplicate, a scope that is not one, an activity that is not one, a
+* cap out of range. A declaration that reached a request would be refused there, by a caller, in a way only
+* the operator can fix.
+*
+* **A room kind's scope is one the capability's own admin routes already require, and only `GET`s require
+* it** — compared against `adminRoutes`, the same artifact `capabilityHealthSources` polices health keys
+* with, and for the same reason. `pithy dashboard connect` offers the scopes it reads off `adminRoutes`, so
+* a scope no route requires — one of presence's own, a near-miss, another capability's — is never offered
+* and never in the default grant, and the room is unjoinable from every management client with no error to
+* say why. And a scope that also gates a write would make joining a room need a mutation grant, which
+* inverts the read rule `grant.ts` applies.
+*/
+function assertPresenceDeclaration(capability, presence, adminRoutes) {
+	const refuse = (detail) => {
+		throw new InternalError({
+			message: `${capability} declares presence rooms this Worker cannot serve.`,
+			action: `Fix the presence declaration on the ${capability} capability.`,
+			detail
+		});
+	};
+	if (!presence.basePath.startsWith("/") || presence.basePath.endsWith("/")) refuse(`presence basePath "${presence.basePath}" must start with "/" and not end with one`);
+	const seen = /* @__PURE__ */ new Set();
+	for (const room of presence.rooms) {
+		if (!PresenceRoomKindName.safeParse(room.kind).success) refuse(`room kind "${room.kind}" is not a kind name`);
+		if (!room.kind.startsWith(`${capability}.`)) refuse(`room kind "${room.kind}" must start with "${capability}." — a capability declares kinds under its own name`);
+		if (seen.has(room.kind)) refuse(`room kind "${room.kind}" is declared twice`);
+		seen.add(room.kind);
+		if (!ControlPlaneScope.safeParse(room.scope).success) refuse(`room kind "${room.kind}" scope "${room.scope}" is not a scope`);
+		const gating = adminRoutes.filter((route) => route.scope === room.scope);
+		if (gating.length === 0) refuse(`room kind "${room.kind}" scope "${room.scope}": no admin route of ${capability} requires it, so no grant would ever offer it`);
+		const write = gating.find((route) => route.method !== "GET");
+		if (write) refuse(`room kind "${room.kind}" scope "${room.scope}" gates a ${write.method}; a room joins with a read scope, one only GET routes require`);
+		if (room.activities.length === 0 || room.activities.length > 16) refuse(`room kind "${room.kind}" declares ${room.activities.length} activities; it needs 1 to 16`);
+		if (new Set(room.activities).size !== room.activities.length) refuse(`room kind "${room.kind}" declares an activity twice`);
+		for (const activity of room.activities) if (!PresenceActivity.safeParse(activity).success) refuse(`room kind "${room.kind}" activity "${activity}" is not one word`);
+		const cap = participantCap(room);
+		if (!Number.isInteger(cap) || cap < 1 || cap > 100) refuse(`room kind "${room.kind}" maxParticipants ${cap} is outside 1 to 100`);
+	}
+}
+/**
+* The ticket signing keys, resolved and non-empty — the first signs, every one verifies. A blank entry is
+* dropped rather than tried, since WebCrypto refuses a zero-length key with an error that names nothing.
+*/
+async function resolveTicketKeys(key, env) {
+	const resolved = typeof key === "function" ? await key(env) : key;
+	const keys = (typeof resolved === "string" ? [resolved] : [...resolved]).filter((value) => value.length > 0);
+	if (keys.length === 0) throw new InternalError({
+		message: "Presence is not available right now.",
+		action: `Set ${PRESENCE_TICKET_KEY_SECRET}. ${remedy("secrets provision", {}, { runtime: true }).say((command) => `${command} mints it for each environment.`)}`,
+		detail: `${PRESENCE_TICKET_KEY_SECRET} resolved to no usable value`
+	});
+	return keys;
+}
+//#endregion
+export { DEFAULT_PRESENCE_PARTICIPANTS, MAX_PRESENCE_ACTIVITIES, MAX_PRESENCE_PARTICIPANTS, PRESENCE_MAX_FRAME_BYTES, PRESENCE_ROOMS_BINDING, PRESENCE_ROOMS_BINDING_SPEC, PRESENCE_ROOM_CLASS, PRESENCE_ROOM_MODULE, PRESENCE_TICKET_KEY_ENTRY, PRESENCE_TICKET_KEY_SECRET, PRESENCE_TICKET_TTL_SECONDS, assertPresenceDeclaration, participantCap, presenceRoomPath, presenceSocketPath, presenceTicketPath, resolveTicketKeys, sessionParticipantName };

package/dist/presence/durableObject.d.ts

@@ -0,0 +1,61 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { DurableObject } from "cloudflare:workers";
+/**
+ * **One presence room: who has one record open, and what they are doing.** Addressed by `<kind>:<recordId>`,
+ * so each record has its own object.
+ *
+ * The Hibernation API only: `ctx.acceptWebSocket`, never `ws.accept()`, and no registry of sockets in
+ * memory — the participants are read back from `getWebSockets()`, each from its own attachment, so a room
+ * that hibernates and wakes knows exactly who is in it. Nothing is written to Durable Object storage: the
+ * room holds nothing but who is here, and when the last socket closes it is gone.
+ *
+ * The upgrade is forwarded by the Worker's socket route, which has verified the ticket and states the
+ * admission on {@link PRESENCE_ADMISSION_HEADER}. The room trusts that header — a Durable Object is reached
+ * only through its binding — and decides the two things only it can: whether the ticket is already spent, and
+ * whether the room is full.
+ */
+export declare class PresenceRoom extends DurableObject<Record<string, unknown>> {
+    /**
+     * Tickets redeemed by sockets that closed while no other socket was left to carry them. Memory, not
+     * storage, and only while the room is empty: the next socket to join takes them into its attachment, and
+     * until one does, {@link awake} keeps the room from hibernating and losing them.
+     */
+    private remembered;
+    /**
+     * The timer that holds an empty room awake until the last remembered ticket would expire. A Durable Object
+     * with no socket hibernates after about ten seconds idle and loses its memory, which would let a spent
+     * ticket in again; a pending timer is one of the things that stops it. With no timer, an idle object that
+     * cannot hibernate is evicted only after 70 seconds or more — past a 60-second ticket's life. A deploy or a
+     * restart still clears it, and drops every socket with it.
+     */
+    private awake;
+    fetch(request: Request): Promise<Response>;
+    /**
+     * One frame from a participant: `ping`, or `set_activity` naming an activity the room kind declares. A frame
+     * past the size limit, one that does not parse, and an undeclared activity are each answered with an error
+     * frame and change nothing.
+     */
+    webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): Promise<void>;
+    webSocketClose(ws: WebSocket): Promise<void>;
+    webSocketError(ws: WebSocket): Promise<void>;
+    /** A socket leaves: everyone else hears it, and the ticket it spent stays spent. */
+    private leave;
+    /**
+     * Hold the room awake until the last remembered ticket would expire, or let it sleep when there is none.
+     * The timer wakes once that has passed and lets go.
+     */
+    private stayAwake;
+    /** Send a frame to every participant but one. One dead socket never blocks the rest. */
+    private broadcast;
+    /** The open sockets the runtime holds for this room. */
+    private sockets;
+    /** The attachments of sockets the runtime still holds but that are no longer open. */
+    private leavingAttachments;
+    /** Every participant's attachment, read back from the runtime. */
+    private attachments;
+    private attachmentOf;
+    /** The admission the Worker forwarded. Missing or malformed is a request that did not come through the route. */
+    private admission;
+}
+//# sourceMappingURL=durableObject.d.ts.map

package/dist/presence/durableObject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durableObject.d.ts","sourceRoot":"","sources":["../../src/presence/durableObject.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AA8BnD;;;;;;;;;;;;;GAaG;AACH,qBAAa,YAAa,SAAQ,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtE;;;;OAIG;IACH,OAAO,CAAC,UAAU,CAAqB;IAEvC;;;;;;OAMG;IACH,OAAO,CAAC,KAAK,CAAwE;IAEtE,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CA0DxD;IAED;;;;OAIG;IACY,gBAAgB,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CA2C3F;IAEc,cAAc,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAE1D;IAEc,cAAc,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAE1D;IAED,oFAAoF;IACpF,OAAO,CAAC,KAAK;IAyBb;;;OAGG;IACH,OAAO,CAAC,SAAS;IAiBjB,wFAAwF;IACxF,OAAO,CAAC,SAAS;IAYjB,wDAAwD;IACxD,OAAO,CAAC,OAAO;IAIf,sFAAsF;IACtF,OAAO,CAAC,kBAAkB;IAQ1B,kEAAkE;IAClE,OAAO,CAAC,WAAW;IAOnB,OAAO,CAAC,YAAY;IAKpB,iHAAiH;IACjH,OAAO,CAAC,SAAS;CAYlB"}

package/dist/presence/durableObject.js

@@ -0,0 +1,257 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { PithyError, PresenceRoomFullError, PresenceTicketInvalidError, ValidationError, fromZodError } from "../error/pithyError.js";
+import { PRESENCE_ROOM_VERSIONS, PresenceRoomClientFrame, PresenceRoomPing, PresenceRoomPong } from "./frames.js";
+import { PRESENCE_MAX_FRAME_BYTES } from "./declaration.js";
+import { SUBPROTOCOL_HEADER, negotiateSubprotocol } from "../http/subprotocol.js";
+import { PRESENCE_ADMISSION_HEADER, PresenceAdmission, PresenceAttachment, admit, carrySpent, declaresActivity, inheritSpent } from "./room.js";
+import { clientError } from "../error/client.js";
+import { DurableObject } from "cloudflare:workers";
+//#region src/presence/durableObject.ts
+/**
+* **One presence room: who has one record open, and what they are doing.** Addressed by `<kind>:<recordId>`,
+* so each record has its own object.
+*
+* The Hibernation API only: `ctx.acceptWebSocket`, never `ws.accept()`, and no registry of sockets in
+* memory — the participants are read back from `getWebSockets()`, each from its own attachment, so a room
+* that hibernates and wakes knows exactly who is in it. Nothing is written to Durable Object storage: the
+* room holds nothing but who is here, and when the last socket closes it is gone.
+*
+* The upgrade is forwarded by the Worker's socket route, which has verified the ticket and states the
+* admission on {@link PRESENCE_ADMISSION_HEADER}. The room trusts that header — a Durable Object is reached
+* only through its binding — and decides the two things only it can: whether the ticket is already spent, and
+* whether the room is full.
+*/
+var PresenceRoom = class extends DurableObject {
+	/**
+	* Tickets redeemed by sockets that closed while no other socket was left to carry them. Memory, not
+	* storage, and only while the room is empty: the next socket to join takes them into its attachment, and
+	* until one does, {@link awake} keeps the room from hibernating and losing them.
+	*/
+	remembered = [];
+	/**
+	* The timer that holds an empty room awake until the last remembered ticket would expire. A Durable Object
+	* with no socket hibernates after about ten seconds idle and loses its memory, which would let a spent
+	* ticket in again; a pending timer is one of the things that stops it. With no timer, an idle object that
+	* cannot hibernate is evicted only after 70 seconds or more — past a 60-second ticket's life. A deploy or a
+	* restart still clears it, and drops every socket with it.
+	*/
+	awake = null;
+	async fetch(request) {
+		if (request.headers.get("upgrade") !== "websocket") return new Response("Expected a WebSocket upgrade.", { status: 426 });
+		try {
+			const admission = this.admission(request);
+			const version = negotiateSubprotocol(request.headers.get(SUBPROTOCOL_HEADER), PRESENCE_ROOM_VERSIONS);
+			if (version === null) throw new ValidationError({ message: "Offer pithy.presence.v1." });
+			const now = /* @__PURE__ */ new Date();
+			const nowSeconds = Math.floor(now.getTime() / 1e3);
+			const present = this.attachments();
+			const leaving = this.leavingAttachments().flatMap((attachment) => [attachment.ticket, ...attachment.spent]);
+			const refusal = admit(admission, present, [...this.remembered, ...leaving], nowSeconds);
+			if (refusal === "spent") throw new PresenceTicketInvalidError({ detail: `ticket ${admission.ticket.id} is spent` });
+			if (refusal === "full") throw new PresenceRoomFullError({ detail: `${admission.kind}/${admission.recordId} at ${admission.maxParticipants}` });
+			const participant = {
+				id: crypto.randomUUID(),
+				ref: admission.ref,
+				name: admission.name,
+				origin: admission.origin,
+				activity: admission.activities[0],
+				joinedAt: now.toISOString()
+			};
+			const pair = new WebSocketPair();
+			const [client, server] = [pair[0], pair[1]];
+			this.ctx.acceptWebSocket(server);
+			server.serializeAttachment({
+				participant,
+				version,
+				ticket: admission.ticket,
+				activities: admission.activities,
+				spent: inheritSpent(this.remembered, admission.ticket.id, nowSeconds)
+			});
+			this.remembered = [];
+			this.stayAwake(nowSeconds);
+			const everyone = [...present.map((attachment) => attachment.participant), participant].sort((a, b) => a.joinedAt.localeCompare(b.joinedAt));
+			server.send(render({
+				type: "init",
+				self: participant.id,
+				participants: everyone
+			}));
+			this.broadcast({
+				type: "joined",
+				participant
+			}, server);
+			return new Response(null, {
+				status: 101,
+				webSocket: client,
+				headers: { [SUBPROTOCOL_HEADER]: version }
+			});
+		} catch (error) {
+			if (!(error instanceof PithyError)) throw error;
+			return Response.json({ error: clientError(error.payload) }, { status: error.payload.status });
+		}
+	}
+	/**
+	* One frame from a participant: `ping`, or `set_activity` naming an activity the room kind declares. A frame
+	* past the size limit, one that does not parse, and an undeclared activity are each answered with an error
+	* frame and change nothing.
+	*/
+	async webSocketMessage(ws, message) {
+		const attachment = this.attachmentOf(ws);
+		if (!attachment) return;
+		const bytes = typeof message === "string" ? new TextEncoder().encode(message).byteLength : message.byteLength;
+		try {
+			if (bytes > 1024) throw new ValidationError({
+				message: `A frame is at most ${PRESENCE_MAX_FRAME_BYTES} bytes.`,
+				detail: `${bytes} bytes`
+			});
+			const text = typeof message === "string" ? message : new TextDecoder().decode(message);
+			if (PresenceRoomPing.safeParse(text).success) {
+				ws.send(PresenceRoomPong.value);
+				return;
+			}
+			let json;
+			try {
+				json = JSON.parse(text);
+			} catch {
+				throw new ValidationError({ message: "This socket accepts `ping` and JSON frames." });
+			}
+			const parsed = PresenceRoomClientFrame.safeParse(json);
+			if (!parsed.success) throw fromZodError(parsed.error, { message: "This socket accepts `set_activity`." });
+			const frame = parsed.data;
+			if (!declaresActivity(attachment, frame.activity)) throw new ValidationError({
+				message: `This room's activities are ${attachment.activities.join(", ")}.`,
+				params: { activity: frame.activity }
+			});
+			if (frame.activity === attachment.participant.activity) return;
+			const participant = {
+				...attachment.participant,
+				activity: frame.activity
+			};
+			ws.serializeAttachment({
+				...attachment,
+				participant
+			});
+			this.broadcast({
+				type: "activity",
+				participantId: participant.id,
+				activity: frame.activity
+			}, ws);
+		} catch (error) {
+			if (!(error instanceof PithyError)) throw error;
+			try {
+				ws.send(render({
+					type: "error",
+					error: clientError(error.payload)
+				}));
+			} catch {}
+		}
+	}
+	async webSocketClose(ws) {
+		this.leave(ws);
+	}
+	async webSocketError(ws) {
+		this.leave(ws);
+	}
+	/** A socket leaves: everyone else hears it, and the ticket it spent stays spent. */
+	leave(ws) {
+		const closing = this.attachmentOf(ws);
+		if (closing) {
+			const nowSeconds = Math.floor(Date.now() / 1e3);
+			const [carrier] = this.sockets().filter((other) => other !== ws);
+			const carried = carrier ? this.attachmentOf(carrier) : void 0;
+			if (carrier && carried) {
+				const spent = carrySpent(carried, closing, nowSeconds);
+				if (spent) carrier.serializeAttachment({
+					...carried,
+					spent
+				});
+			} else {
+				this.remembered = [
+					...this.remembered,
+					closing.ticket,
+					...closing.spent
+				];
+				this.stayAwake(nowSeconds);
+			}
+			ws.serializeAttachment(null);
+			this.broadcast({
+				type: "left",
+				participantId: closing.participant.id
+			}, ws);
+		}
+		try {
+			ws.close();
+		} catch {}
+	}
+	/**
+	* Hold the room awake until the last remembered ticket would expire, or let it sleep when there is none.
+	* The timer wakes once that has passed and lets go.
+	*/
+	stayAwake(nowSeconds) {
+		this.remembered = this.remembered.filter((ticket) => ticket.exp > nowSeconds);
+		const until = Math.max(0, ...this.remembered.map((ticket) => ticket.exp));
+		if (this.awake && this.remembered.length > 0 && this.awake.until >= until) return;
+		if (this.awake) clearTimeout(this.awake.timer);
+		this.awake = null;
+		if (this.remembered.length === 0) return;
+		const timer = setTimeout(() => {
+			this.awake = null;
+			this.stayAwake(Math.floor(Date.now() / 1e3));
+		}, (until - nowSeconds + 1) * 1e3);
+		this.awake = {
+			until,
+			timer
+		};
+	}
+	/** Send a frame to every participant but one. One dead socket never blocks the rest. */
+	broadcast(frame, except) {
+		const text = render(frame);
+		for (const ws of this.sockets()) {
+			if (ws === except || !this.attachmentOf(ws)) continue;
+			try {
+				ws.send(text);
+			} catch {}
+		}
+	}
+	/** The open sockets the runtime holds for this room. */
+	sockets() {
+		return this.ctx.getWebSockets().filter((ws) => ws.readyState === WebSocket.OPEN);
+	}
+	/** The attachments of sockets the runtime still holds but that are no longer open. */
+	leavingAttachments() {
+		return this.ctx.getWebSockets().flatMap((ws) => {
+			if (ws.readyState === WebSocket.OPEN) return [];
+			const attachment = this.attachmentOf(ws);
+			return attachment ? [attachment] : [];
+		});
+	}
+	/** Every participant's attachment, read back from the runtime. */
+	attachments() {
+		return this.sockets().flatMap((ws) => {
+			const attachment = this.attachmentOf(ws);
+			return attachment ? [attachment] : [];
+		});
+	}
+	attachmentOf(ws) {
+		const parsed = PresenceAttachment.safeParse(ws.deserializeAttachment());
+		return parsed.success ? parsed.data : void 0;
+	}
+	/** The admission the Worker forwarded. Missing or malformed is a request that did not come through the route. */
+	admission(request) {
+		const raw = request.headers.get(PRESENCE_ADMISSION_HEADER);
+		let json;
+		try {
+			json = raw === null ? null : JSON.parse(raw);
+		} catch {
+			json = null;
+		}
+		const parsed = PresenceAdmission.safeParse(json);
+		if (!parsed.success) throw new PresenceTicketInvalidError({ detail: "no admission on the forwarded upgrade" });
+		return parsed.data;
+	}
+};
+function render(frame) {
+	return JSON.stringify(frame);
+}
+//#endregion
+export { PresenceRoom };