@pithy-sh/core 0.13.0 → 0.15.0

package/dist/presence/room.d.ts

@@ -0,0 +1,95 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+/**
+ * **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 declare const SpentTicket: z.ZodObject<{
+    id: z.ZodString;
+    exp: z.ZodNumber;
+}, z.core.$strip>;
+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 declare const PresenceAdmission: z.ZodObject<{
+    kind: z.ZodString;
+    recordId: z.ZodString;
+    ref: z.ZodString;
+    name: z.ZodString;
+    origin: z.ZodEnum<{
+        "control-plane": "control-plane";
+        session: "session";
+    }>;
+    ticket: z.ZodObject<{
+        id: z.ZodString;
+        exp: z.ZodNumber;
+    }, z.core.$strip>;
+    activities: z.ZodArray<z.ZodString>;
+    maxParticipants: z.ZodNumber;
+}, z.core.$strip>;
+export type PresenceAdmission = z.infer<typeof PresenceAdmission>;
+/** The server-set header carrying a {@link PresenceAdmission} into the room. */
+export declare const PRESENCE_ADMISSION_HEADER = "x-pithy-presence-admission";
+/** What one socket carries through hibernation. Kept far under the 16,384-byte attachment ceiling. */
+export declare const PresenceAttachment: z.ZodObject<{
+    participant: z.ZodObject<{
+        id: z.ZodString;
+        ref: z.ZodString;
+        name: z.ZodString;
+        origin: z.ZodEnum<{
+            "control-plane": "control-plane";
+            session: "session";
+        }>;
+        activity: z.ZodString;
+        joinedAt: z.ZodISODateTime;
+    }, z.core.$strip>;
+    version: z.ZodString;
+    ticket: z.ZodObject<{
+        id: z.ZodString;
+        exp: z.ZodNumber;
+    }, z.core.$strip>;
+    activities: z.ZodArray<z.ZodString>;
+    spent: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        exp: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PresenceAttachment = z.infer<typeof PresenceAttachment>;
+/** Every ticket a room still remembers as spent, from its sockets' attachments and its own memory. */
+export declare function spentTickets(attachments: readonly PresenceAttachment[], remembered: readonly SpentTicket[], nowSeconds: number): Set<string>;
+/** 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 declare function admit(admission: PresenceAdmission, attachments: readonly PresenceAttachment[], remembered: readonly SpentTicket[], nowSeconds: number): AdmissionRefusal;
+/**
+ * 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 declare const MAX_CARRIED_SPENT = 160;
+/**
+ * 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 declare function inheritSpent(remembered: readonly SpentTicket[], own: string, nowSeconds: number): SpentTicket[];
+/**
+ * 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 declare function carrySpent(survivor: PresenceAttachment, closing: PresenceAttachment, nowSeconds: number): SpentTicket[] | null;
+/** Whether a client may announce this activity in this room. */
+export declare function declaresActivity(attachment: PresenceAttachment, activity: string): boolean;
+//# sourceMappingURL=room.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"room.d.ts","sourceRoot":"","sources":["../../src/presence/room.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;;GAUG;AAEH,+GAA+G;AAC/G,eAAO,MAAM,WAAW;;;iBAKsD,CAAC;AAC/E,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD;;;GAGG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;iBAc4D,CAAC;AAC3F,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE,gFAAgF;AAChF,eAAO,MAAM,yBAAyB,+BAA+B,CAAC;AAEtE,sGAAsG;AACtG,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;iBAU0D,CAAC;AAC1F,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEpE,sGAAsG;AACtG,wBAAgB,YAAY,CAC1B,WAAW,EAAE,SAAS,kBAAkB,EAAE,EAC1C,UAAU,EAAE,SAAS,WAAW,EAAE,EAClC,UAAU,EAAE,MAAM,GACjB,GAAG,CAAC,MAAM,CAAC,CAWb;AAED,2DAA2D;AAC3D,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,MAAM,GAAG,IAAI,CAAC;AAEvD,0DAA0D;AAC1D,wBAAgB,KAAK,CACnB,SAAS,EAAE,iBAAiB,EAC5B,WAAW,EAAE,SAAS,kBAAkB,EAAE,EAC1C,UAAU,EAAE,SAAS,WAAW,EAAE,EAClC,UAAU,EAAE,MAAM,GACjB,gBAAgB,CAIlB;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAYrC;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,SAAS,WAAW,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,WAAW,EAAE,CAE/G;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,kBAAkB,EAC3B,UAAU,EAAE,MAAM,GACjB,WAAW,EAAE,GAAG,IAAI,CAKtB;AAED,gEAAgE;AAChE,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE1F"}

package/dist/presence/room.js

@@ -0,0 +1,105 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { PresenceActivity, PresenceRecordId, PresenceRoomKindName } from "./names.js";
+import { PresenceOrigin, PresenceParticipant, PresenceParticipantName, PresenceParticipantRef } from "./frames.js";
+import { z } from "zod";
+//#region src/presence/room.ts
+/**
+* **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. */
+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.");
+/**
+* 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.
+*/
+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.");
+/** The server-set header carrying a {@link PresenceAdmission} into the room. */
+const PRESENCE_ADMISSION_HEADER = "x-pithy-presence-admission";
+/** What one socket carries through hibernation. Kept far under the 16,384-byte attachment ceiling. */
+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.");
+/** Every ticket a room still remembers as spent, from its sockets' attachments and its own memory. */
+function spentTickets(attachments, remembered, nowSeconds) {
+	const spent = /* @__PURE__ */ new Set();
+	const add = (ticket) => {
+		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;
+}
+/** Decide one admission against the room as it stands. */
+function admit(admission, attachments, remembered, nowSeconds) {
+	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.
+*/
+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, own, nowSeconds) {
+	const byId = /* @__PURE__ */ new Map();
+	for (const ticket of tickets) if (ticket.exp > nowSeconds && ticket.id !== own) byId.set(ticket.id, ticket);
+	const live = [...byId.values()];
+	return live.length > 160 ? live.sort((a, b) => b.exp - a.exp).slice(0, 160) : 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.
+*/
+function inheritSpent(remembered, own, nowSeconds) {
+	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.
+*/
+function carrySpent(survivor, closing, nowSeconds) {
+	const next = liveSpent([
+		...survivor.spent,
+		closing.ticket,
+		...closing.spent
+	], survivor.ticket.id, nowSeconds);
+	return next.length === survivor.spent.length && next.every((ticket, index) => survivor.spent[index]?.id === ticket.id) ? null : next;
+}
+/** Whether a client may announce this activity in this room. */
+function declaresActivity(attachment, activity) {
+	return attachment.activities.includes(activity);
+}
+//#endregion
+export { MAX_CARRIED_SPENT, PRESENCE_ADMISSION_HEADER, PresenceAdmission, PresenceAttachment, SpentTicket, admit, carrySpent, declaresActivity, inheritSpent, spentTickets };

package/dist/presence/ticket.d.ts

@@ -0,0 +1,55 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+/**
+ * **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 declare const PRESENCE_TICKET_PROTOCOL_PREFIX = "pithy.ticket.";
+/** What a ticket says, signed. */
+export declare const PresenceTicketClaims: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    id: z.ZodString;
+    kind: z.ZodString;
+    recordId: z.ZodString;
+    ref: z.ZodString;
+    name: z.ZodString;
+    origin: z.ZodEnum<{
+        "control-plane": "control-plane";
+        session: "session";
+    }>;
+    exp: z.ZodNumber;
+}, z.core.$strip>;
+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">;
+/** Mint a ticket. `keys[0]` signs. */
+export declare function mintPresenceTicket(request: PresenceTicketRequest, keys: readonly string[], now?: Date): Promise<{
+    ticket: string;
+    claims: PresenceTicketClaims;
+}>;
+/**
+ * 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 declare function verifyPresenceTicket(ticket: string, room: {
+    kind: string;
+    recordId: string;
+}, keys: readonly string[], now?: Date): Promise<PresenceTicketClaims>;
+/**
+ * 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 declare function ticketFromOffer(offered: string | null | undefined): string | undefined;
+//# sourceMappingURL=ticket.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ticket.d.ts","sourceRoot":"","sources":["../../src/presence/ticket.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAOxB;;;;;;;;;;;;;GAaG;AAEH,iFAAiF;AACjF,eAAO,MAAM,+BAA+B,kBAAkB,CAAC;AAE/D,kCAAkC;AAClC,eAAO,MAAM,oBAAoB;;;;;;;;;;;;iBAawD,CAAC;AAC1F,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE,uGAAuG;AACvG,MAAM,MAAM,qBAAqB,GAAG,IAAI,CAAC,oBAAoB,EAAE,GAAG,GAAG,IAAI,GAAG,KAAK,CAAC,CAAC;AAWnF,sCAAsC;AACtC,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,qBAAqB,EAC9B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,GAAG,GAAE,IAAiB,GACrB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,oBAAoB,CAAA;CAAE,CAAC,CAY3D;AAWD;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,EACxC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,GAAG,GAAE,IAAiB,GACrB,OAAO,CAAC,oBAAoB,CAAC,CAqC/B;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAOtF"}

package/dist/presence/ticket.js

@@ -0,0 +1,109 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { PresenceTicketInvalidError } from "../error/pithyError.js";
+import { PresenceRecordId, PresenceRoomKindName } from "./names.js";
+import { PresenceOrigin, PresenceParticipantName, PresenceParticipantRef } from "./frames.js";
+import "./declaration.js";
+import { base64UrlDecode, base64UrlEncode } from "../controlPlane/token/base64url.js";
+import { z } from "zod";
+//#region src/presence/ticket.ts
+/**
+* **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`. */
+const PRESENCE_TICKET_PROTOCOL_PREFIX = "pithy.ticket.";
+/** What a ticket says, signed. */
+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.");
+const encoder = new TextEncoder();
+async function hmacKey(secret) {
+	return crypto.subtle.importKey("raw", encoder.encode(secret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign", "verify"]);
+}
+/** Mint a ticket. `keys[0]` signs. */
+async function mintPresenceTicket(request, keys, now = /* @__PURE__ */ new Date()) {
+	const [signing] = keys;
+	if (signing === void 0) throw new PresenceTicketInvalidError({ detail: "no signing key" });
+	const claims = PresenceTicketClaims.parse({
+		v: 1,
+		id: crypto.randomUUID(),
+		...request,
+		exp: Math.floor(now.getTime() / 1e3) + 60
+	});
+	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, what) {
+	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.
+*/
+async function verifyPresenceTicket(ticket, room, keys, now = /* @__PURE__ */ new Date()) {
+	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;
+	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() / 1e3);
+	if (claims.exp <= seconds) throw new PresenceTicketInvalidError({ detail: `expired at ${claims.exp}` });
+	if (claims.exp > seconds + 60) 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.
+*/
+function ticketFromOffer(offered) {
+	const tickets = (offered ?? "").split(",").map((protocol) => protocol.trim()).filter((protocol) => protocol.startsWith(PRESENCE_TICKET_PROTOCOL_PREFIX)).map((protocol) => protocol.slice(13));
+	return tickets.length === 1 ? tickets[0] : void 0;
+}
+//#endregion
+export { PRESENCE_TICKET_PROTOCOL_PREFIX, PresenceTicketClaims, mintPresenceTicket, ticketFromOffer, verifyPresenceTicket };

package/dist/privacy/classify.js

@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
-import { SQLiteBoolean, SQLiteDate, isSqliteJson } from "../data/codecs.js";
 import { ownPrivacyClasses, privacyClasses, rankPrivacyClasses, strongestPrivacyClass } from "./classes.js";
+import { SQLiteBoolean, SQLiteDate, isSqliteJson } from "../data/codecs.js";
 //#region src/privacy/classify.ts
 /**
 * **The one recursion limit**, shared by `redact`, `classifyPrivacy` and `Redacted<T>` (`./types` reads this constant's

package/dist/privacy/encrypted.js

@@ -1,9 +1,9 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 import { ValidationError } from "../error/pithyError.js";
+import { PRIVACY_META_KEY, rankPrivacyClasses } from "./classes.js";
 import { EncryptedEnvelope } from "../crypto/envelope.js";
 import { isSqliteJson, sqliteJson } from "../data/codecs.js";
-import { PRIVACY_META_KEY, rankPrivacyClasses } from "./classes.js";
 import { classifyPrivacy } from "./classify.js";
 import { z } from "zod";
 import { CamelCasePlugin } from "kysely";

package/dist/processing/activity.d.ts

@@ -0,0 +1,134 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { z } from "zod";
+import { type BasisSource, LegalBasis } from "./vocabulary";
+/**
+ * Processing activities: what a Worker does with personal data, why, and on what legal basis — the declarations the
+ * GDPR Article 30 record is derived from.
+ *
+ * ## Declared where the processing is
+ *
+ * A capability states the activities it performs, under its own `name` (`auth.account`), the rule consent purposes,
+ * tables and error codes follow. The adopter adds their own in the `processing` block of a Worker's
+ * `pithy.config.ts`, and may replace a capability's legal basis there.
+ *
+ * ## A missing basis is a gap, never a guess
+ *
+ * `legalBasis` is optional. An activity without one is reported as a gap in the record, and nothing fills it in.
+ */
+/** An activity id: `<domain>.<name>`, lowercase, the domain being the declaring capability's name. */
+export declare const ProcessingActivityId: z.ZodString;
+export type ProcessingActivityId = z.infer<typeof ProcessingActivityId>;
+/** Someone outside the Worker's own code who receives personal data for an activity. */
+export declare const ProcessingRecipient: z.ZodObject<{
+    name: z.ZodString;
+    receives: z.ZodString;
+    classes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type ProcessingRecipient = z.output<typeof ProcessingRecipient>;
+export type ProcessingRecipientInput = z.input<typeof ProcessingRecipient>;
+/** One processing activity, as a capability or the adopter declares it. */
+export declare const ProcessingActivity: z.ZodObject<{
+    id: z.ZodString;
+    purpose: z.ZodString;
+    classes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    legalBasis: z.ZodOptional<z.ZodEnum<{
+        consent: "consent";
+        contract: "contract";
+        "legal-obligation": "legal-obligation";
+        "legitimate-interests": "legitimate-interests";
+        "public-task": "public-task";
+        "vital-interests": "vital-interests";
+    }>>;
+    consentPurpose: z.ZodOptional<z.ZodString>;
+    recipients: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        receives: z.ZodString;
+        classes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ProcessingActivity = z.output<typeof ProcessingActivity>;
+export type ProcessingActivityInput = z.input<typeof ProcessingActivity>;
+/** The adopter's replacement for a capability's legal basis. */
+export declare const ProcessingOverride: z.ZodObject<{
+    legalBasis: z.ZodEnum<{
+        consent: "consent";
+        contract: "contract";
+        "legal-obligation": "legal-obligation";
+        "legitimate-interests": "legitimate-interests";
+        "public-task": "public-task";
+        "vital-interests": "vital-interests";
+    }>;
+    consentPurpose: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type ProcessingOverride = z.infer<typeof ProcessingOverride>;
+/** The `processing` block, as a Worker's `pithy.config.ts` writes it. */
+export declare const ProcessingPolicy: z.ZodObject<{
+    activities: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        purpose: z.ZodString;
+        classes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        legalBasis: z.ZodOptional<z.ZodEnum<{
+            consent: "consent";
+            contract: "contract";
+            "legal-obligation": "legal-obligation";
+            "legitimate-interests": "legitimate-interests";
+            "public-task": "public-task";
+            "vital-interests": "vital-interests";
+        }>>;
+        consentPurpose: z.ZodOptional<z.ZodString>;
+        recipients: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            receives: z.ZodString;
+            classes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
+    overrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        legalBasis: z.ZodEnum<{
+            consent: "consent";
+            contract: "contract";
+            "legal-obligation": "legal-obligation";
+            "legitimate-interests": "legitimate-interests";
+            "public-task": "public-task";
+            "vital-interests": "vital-interests";
+        }>;
+        consentPurpose: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type ProcessingPolicy = z.output<typeof ProcessingPolicy>;
+export type ProcessingPolicyInput = z.input<typeof ProcessingPolicy>;
+/** The domain half of an activity id: `auth` for `auth.account`. */
+export declare function activityDomain(id: string): string;
+/**
+ * Parse one declarer's activities and refuse what the record could not attribute: an invalid activity, one under a
+ * domain that is not the declarer's, or two with one id. `domain` is the declaring capability's name, or `null` for
+ * the adopter's own, which may use any domain but a reserved one.
+ */
+export declare function parseProcessingActivities(declarer: string, activities: readonly ProcessingActivityInput[], domain: string | null, reserved?: ReadonlySet<string>): ProcessingActivity[];
+/** Parse a `processing` block, or refuse it naming what is wrong. `undefined` is the empty policy. */
+export declare function parseProcessingPolicy(input: unknown): ProcessingPolicy;
+/** One activity as it takes effect: who declared it, its basis after any override, and where that came from. */
+export interface ResolvedActivity {
+    readonly id: string;
+    readonly purpose: string;
+    readonly classes: readonly string[];
+    readonly legalBasis: LegalBasis | null;
+    readonly basisSource: BasisSource | null;
+    readonly consentPurpose: string | null;
+    readonly recipients: readonly ProcessingRecipient[];
+    /** The capability that declared it, or `config` for the adopter's own. */
+    readonly declaredBy: string;
+}
+/** What resolving reads off a composed capability. */
+interface ActivityDeclarer {
+    readonly name: string;
+    readonly processing?: readonly ProcessingActivity[];
+}
+/**
+ * Every activity as it takes effect over a composition: each capability's, in composition order, then the adopter's,
+ * with the block's overrides applied. Refuses an adopter activity under a composed capability's domain, an id declared
+ * twice, and an override naming an activity no composed capability declares. Called when a Worker assembles.
+ */
+export declare function resolveProcessing(policy: ProcessingPolicy, capabilities: readonly ActivityDeclarer[]): ResolvedActivity[];
+export {};
+//# sourceMappingURL=activity.d.ts.map

package/dist/processing/activity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity.d.ts","sourceRoot":"","sources":["../../src/processing/activity.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EAAE,KAAK,WAAW,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE5D;;;;;;;;;;;;;GAaG;AAEH,sGAAsG;AACtG,eAAO,MAAM,oBAAoB,aAS9B,CAAC;AACJ,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE,wFAAwF;AACxF,eAAO,MAAM,mBAAmB;;;;iBAiBkE,CAAC;AACnG,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AACvE,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAiB3E,2EAA2E;AAC3E,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;iBA8BmF,CAAC;AACnH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;AACrE,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEzE,gEAAgE;AAChE,eAAO,MAAM,kBAAkB;;;;;;;;;;kBAS4E,CAAC;AAC5G,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEpE,yEAAyE;AACzE,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAgByF,CAAC;AACvH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AACjE,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAErE,oEAAoE;AACpE,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAGjD;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,SAAS,uBAAuB,EAAE,EAC9C,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,QAAQ,GAAE,WAAW,CAAC,MAAM,CAAa,GACxC,kBAAkB,EAAE,CAkCtB;AAED,sGAAsG;AACtG,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAUtE;AAED,gHAAgH;AAChH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACpD,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,sDAAsD;AACtD,UAAU,gBAAgB;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACrD;AAgBD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,gBAAgB,EACxB,YAAY,EAAE,SAAS,gBAAgB,EAAE,GACxC,gBAAgB,EAAE,CAuCpB"}