@argentic/chest-sdk 0.4.0 → 0.5.0

package/client/index.ts

@@ -1,17 +1,21 @@
-// The package root: every published module a tool's code uses (tool contract
-// 0.4). Each one is also its own subpath (@argentic/chest-sdk/member, /chest,
-// /database, /files, /members, /notifications, /events, /schedules, /ai, /errors), which
-// pulls in nothing else. The files, members, notifications, events, schedules and ai
-// APIs are namespaces here, as their names (get, list, stat, move, notify,
-// verify, chat…) are too plain to stand alone. @argentic/chest-sdk/testing is for a tool's tests only, and
-// is not here.
+// The package root: every published module a tool's server code uses (tool
+// contract 0.5). Each one is also its own subpath (@argentic/chest-sdk/member,
+// /chest, /database, /sealed, /files, /members, /notifications, /events,
+// /schedules, /ai, /realtime, /errors), which pulls in nothing else. The
+// sealed, files, members, notifications, events, schedules, ai and realtime
+// APIs are namespaces here, as their names (seal, open, get, list, stat, move,
+// notify, verify, chat, publish…) are too plain to stand alone.
+// @argentic/chest-sdk/realtime/client runs in the browser, and
+// @argentic/chest-sdk/testing in a tool's tests only: neither is here.
 export * from "./src/errors.js";
 export * from "./src/member.js";
 export * from "./src/chest.js";
 export * from "./src/database.js";
+export * as sealed from "./src/sealed.js";
 export * as files from "./src/files.js";
 export * as members from "./src/members.js";
 export * as notifications from "./src/notifications.js";
 export * as events from "./src/events.js";
 export * as schedules from "./src/schedules.js";
 export * as ai from "./src/ai.js";
+export * as realtime from "./src/realtime.js";

package/client/src/api.ts

@@ -1,4 +1,4 @@
-import { CapabilityNotGranted, ChestError, QuotaExceeded, RateLimited, TooLarge, Unavailable } from "./errors.js";
+import { CapabilityNotGranted, ChestError, QuotaExceeded, RateLimited, StorageFull, TooLarge, Unavailable } from "./errors.js";
 
 // The Chest's API as a server tool reaches it, shared by the modules that
 // call it (files, members): CHEST_API is http://127.0.0.1:<port>, the tool's
@@ -9,21 +9,15 @@ import { CapabilityNotGranted, ChestError, QuotaExceeded, RateLimited, TooLarge,
 const maxAnswer = 4 << 20;
 const deadline = 120000;
 
-// fakeOrigins are the origins of the fake Chests a test started in this
-// process (testing.ts, fakeChest), each http://127.0.0.1:<port>: links and
-// uploads a fake gives on them are taken as the Chest's https ones are. Only
-// the testing module adds to it — the one module no production code
-// imports —, and only for as long as its fake runs; an origin is never read
-// from the environment, so nothing set around a tool widens what it accepts.
-export const fakeOrigins = new Set<string>();
-
 // chestLink reads a link to the team host the Chest answered, at path (its
 // links, its uploads): the token it carries, or undefined for an address
-// that is not one — https, or the origin of a fake Chest of this process.
+// that is not one — https, or the origin of the Chest's API itself
+// (CHEST_API), where only a fake Chest of a tool's tests serves its links:
+// the address the tool already trusts for every call, never another.
 export function chestLink(url: unknown, path: string): string | undefined {
   if (typeof url !== "string") return undefined;
   const found = /^(https:\/\/[A-Za-z0-9.-]{1,253}(?::[0-9]{1,5})?|http:\/\/127\.0\.0\.1:[0-9]{1,5})(\/_chest\/[a-z/]+\/)([A-Za-z0-9_-]+\.[A-Za-z0-9_-]+)$/u.exec(url);
-  if (!found || found[2] !== path || (found[1]!.startsWith("http:") && !fakeOrigins.has(found[1]!))) return undefined;
+  if (!found || found[2] !== path || (found[1]!.startsWith("http:") && found[1] !== process.env["CHEST_API"])) return undefined;
   return found[3];
 }
 
@@ -39,8 +33,8 @@ function base(capability: string): string {
 // is Unavailable. The request and the reading of its answer end after
 // deadline milliseconds (120 seconds unless said), or when the caller's
 // signal aborts: its reason is then thrown.
-export async function ask(capability: string, method: string, path: string, init: { body?: Uint8Array<ArrayBuffer> | string; type?: string; deadline?: number; signal?: AbortSignal } = {}): Promise<Response> {
-  const headers: Record<string, string> = {};
+export async function ask(capability: string, method: string, path: string, init: { body?: Uint8Array<ArrayBuffer> | string; type?: string; headers?: Record<string, string>; deadline?: number; signal?: AbortSignal } = {}): Promise<Response> {
+  const headers: Record<string, string> = { ...init.headers };
   if (init.type !== undefined) headers["Content-Type"] = init.type;
   const url = base(capability) + path;
   const timeout = AbortSignal.timeout(init.deadline ?? deadline);
@@ -86,18 +80,25 @@ export async function json(response: Response): Promise<unknown> {
   }
 }
 
-// refusal turns an answer that is not a success into what the tool tests.
-export async function refusal(response: Response, capability: string): Promise<ChestError> {
-  let code = "refused";
+// errorCode is the code of a refusal of the Chest ({"error": code}), or
+// "refused" for an answer that says none.
+export async function errorCode(response: Response): Promise<string> {
   try {
     const given = ((await json(response)) as { error?: unknown } | null)?.error;
-    if (typeof given === "string" && /^[a-z_]{1,40}$/u.test(given)) code = given;
+    if (typeof given === "string" && /^[a-z_]{1,40}$/u.test(given)) return given;
   } catch {
-    // The code stays "refused".
+    // No code of the Chest's.
   }
+  return "refused";
+}
+
+// refusal turns an answer that is not a success into what the tool tests.
+export async function refusal(response: Response, capability: string): Promise<ChestError> {
+  const code = await errorCode(response);
   if (response.status === 403) return new CapabilityNotGranted(capability);
   if (response.status === 413) return new TooLarge();
   if (response.status === 429) return code === "rate_limited" ? new RateLimited() : new QuotaExceeded();
+  if (response.status === 507 && code === "storage_full") return new StorageFull();
   if (response.status >= 500) return new Unavailable();
   return new ChestError(code, response.status, `the Chest refused: ${code}`);
 }

package/client/src/database.ts

@@ -8,9 +8,14 @@ import { CapabilityNotGranted } from "./errors.js";
 // postgres (porsager) or pg; the SDK carries none. PGHOST, PGPORT, PGUSER,
 // PGPASSWORD and PGDATABASE say the same for a client that reads them.
 //
+// Its user is the tool's role (t_<tool>), or, in the preview of a draft
+// Perseus Code builds, the draft's (pb_<project>: its own empty database).
+//
 // Throws CapabilityNotGranted when the Chest gave no database: the version
 // does not declare it, or a DATABASE_URL of the tool's own is not the
 // Chest's. The value is a secret: never log it, never send it to a browser.
+const role = /^(t_[a-z][a-z0-9_]{0,47}|pb_[a-z2-7]{26})$/u;
+
 export function databaseUrl(): string {
   const value = process.env["DATABASE_URL"];
   if (typeof value !== "string" || value.length > 1024) throw new CapabilityNotGranted("database");
@@ -21,7 +26,7 @@ export function databaseUrl(): string {
     throw new CapabilityNotGranted("database");
   }
   const port = Number(url.port);
-  if (url.protocol !== "postgres:" || url.hostname !== "127.0.0.1" || !Number.isInteger(port) || port < 1 || port > 65535 || !/^t_[a-z][a-z0-9_]{0,47}$/u.test(url.username) || url.pathname !== "/" + url.username || url.password === "" || url.search !== "?sslmode=disable" || url.hash !== "") {
+  if (url.protocol !== "postgres:" || url.hostname !== "127.0.0.1" || !Number.isInteger(port) || port < 1 || port > 65535 || !role.test(url.username) || url.pathname !== "/" + url.username || url.password === "" || url.search !== "?sslmode=disable" || url.hash !== "") {
     throw new CapabilityNotGranted("database");
   }
   return value;

package/client/src/errors.ts

@@ -46,6 +46,15 @@ export class TooLarge extends ChestError {
   }
 }
 
+// The server of the Chest has no more disk for files, whatever the tool's
+// quota: nothing was kept. Its owner frees space or takes a larger server;
+// the tool says the file could not be kept, and may try again later.
+export class StorageFull extends ChestError {
+  constructor() {
+    super("storage_full", 507, "the Chest refused: its server's disk is full");
+  }
+}
+
 // The Chest did not answer, or not as it does: nothing is known of what was
 // asked — a write may or may not have happened.
 export class Unavailable extends ChestError {
@@ -97,3 +106,44 @@ export class AiRefused extends ChestError {
     super("content_refused", 422, "the AI provider refused the content of the request");
   }
 }
+
+// Opening a sealed value needs a member on the request: none came with it,
+// or their ticket expired (a request lasts 60 seconds). A public page, a
+// schedule or an event opens nothing.
+export class MemberRequired extends ChestError {
+  constructor() {
+    super("member_required", 401, "the Chest refused: sealed values open only on the request of a member");
+  }
+}
+
+// The member may not open this: they lost the tool since the request
+// began, or the value was sealed for roles they do not hold.
+export class NotAllowed extends ChestError {
+  constructor() {
+    super("not_allowed", 403, "the Chest refused: this member may not open this value");
+  }
+}
+
+// The sealed value does not open: it was altered, it is another tool's, or
+// it was sealed in another context.
+export class SealedInvalid extends ChestError {
+  constructor() {
+    super("sealed_invalid", 400, "the sealed value does not open: altered, another tool's or of another context");
+  }
+}
+
+// The Chest was restored and its sealed data waits for the owner's recovery
+// code: nothing is sealed or opened until they enter it (Settings).
+export class SealedLocked extends ChestError {
+  constructor() {
+    super("sealed_locked", 503, "the Chest's sealed data is locked until its owner enters the recovery code");
+  }
+}
+
+// The key of this tool's sealed values is lost for good (the Chest key and
+// its recovery code both): its sealed values never open again.
+export class SealedLost extends ChestError {
+  constructor() {
+    super("sealed_lost", 503, "the key of this tool's sealed values is lost");
+  }
+}

package/client/src/eventrules.ts

@@ -0,0 +1,117 @@
+import { groupIdPattern, memberIdPattern } from "./member.js";
+
+// The rules of events between tools, as the Chest applies them
+// (chest/toolevents): what a type, an identifier, an instant, an audience
+// and a declared field are. events reads a delivery and checks an emit with
+// them before sending it; testing's fake Chest refuses what the Chest
+// refuses with them. Not a published module.
+
+// A type: two to four dotted segments of lowercase letters, digits and
+// dashes, each starting with a letter, 64 characters at most; member.* and
+// access.* are the Chest's own (the members' lifecycle).
+const typePattern = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*(?:\.[a-z][a-z0-9]*(?:-[a-z0-9]+)*){1,3}$/u;
+export const isToolEventType = (value: unknown): value is string =>
+  typeof value === "string" && value.length <= 64 && typePattern.test(value) && !value.startsWith("member.") && !value.startsWith("access.");
+
+// An identifier of the publisher's own: the "id" kind of a field, an
+// event's subject and its idempotency key.
+export const itemIdPattern = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
+// The name of a tool, as an event's source.
+export const toolNamePattern = /^[a-z][a-z0-9-]{0,47}$/u;
+// A role of a tool's own (chest.json "roles"), as an audience or a
+// broadcast names it.
+export const rolePattern = /^[a-z][a-z0-9-]{0,47}$/u;
+// A field of an event's data: a camelCase name.
+export const fieldNamePattern = /^[a-z][A-Za-z0-9]{0,39}$/u;
+
+// The largest data of one event, in bytes of its JSON (UTF-8).
+export const maxData = 16 << 10;
+// How far back an event's occurredAt may go — the Chest's 72 hours of
+// retries — and how far ahead the clocks of the Chest and of the container
+// may differ, in milliseconds.
+export const eventWindow = 72 * 3600_000;
+export const clockSkew = 5000;
+
+const daysIn = (year: number, month: number): number => month === 2 ? (year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0) ? 29 : 28) : [4, 6, 9, 11].includes(month) ? 30 : 31;
+const instantPattern = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d{1,9})?(?:Z|[+-](\d{2}):(\d{2}))$/u;
+const datePattern = /^(\d{4})-(\d{2})-(\d{2})$/u;
+
+// instantOf is the time of an RFC 3339 instant (a date, a time to the
+// second or finer, Z or an offset) in milliseconds, or null for anything
+// else — a day or an hour that does not exist included.
+export function instantOf(value: unknown): number | null {
+  const parts = typeof value === "string" ? instantPattern.exec(value) : null;
+  if (!parts) return null;
+  const [year, month, day, hour, minute, second, offsetHour, offsetMinute] = parts.slice(1).map(v => Number(v ?? "0")) as [number, number, number, number, number, number, number, number];
+  if (month < 1 || month > 12 || day < 1 || day > daysIn(year, month) || hour > 23 || minute > 59 || second > 59 || offsetHour > 23 || offsetMinute > 59) return null;
+  return Date.parse(value as string);
+}
+
+// isDate says a value is a day that exists, YYYY-MM-DD.
+export function isDate(value: unknown): boolean {
+  const parts = typeof value === "string" ? datePattern.exec(value) : null;
+  if (!parts) return false;
+  const [year, month, day] = parts.slice(1).map(Number) as [number, number, number];
+  return month >= 1 && month <= 12 && day >= 1 && day <= daysIn(year, month);
+}
+
+// Text: no control character (C0, C1) but line feeds and tabs, no format
+// character (Cf: U+200B, U+202E…) and no unpaired surrogate; no length of
+// its own (the data's 16 KiB bound it).
+const isText = (value: unknown): boolean => typeof value === "string" && !/[^\P{Cc}\n\t]|[\p{Cf}\p{Cs}]/u.test(value);
+
+// The kinds of a declared field, and what a value of each is. A member is
+// one the publisher has or had (known).
+export type FieldKind = "id" | "text" | "number" | "boolean" | "time" | "date" | "member" | "members";
+const kinds: Record<FieldKind, (value: unknown, known: (id: string) => boolean) => boolean> = {
+  id: value => typeof value === "string" && itemIdPattern.test(value),
+  text: isText,
+  number: value => typeof value === "number" && Number.isFinite(value),
+  boolean: value => typeof value === "boolean",
+  time: value => instantOf(value) !== null,
+  date: isDate,
+  member: (value, known) => typeof value === "string" && memberIdPattern.test(value) && known(value),
+  // A list, empty or not, of distinct members.
+  members: (value, known) => Array.isArray(value) && value.every(v => typeof v === "string" && memberIdPattern.test(v) && known(v)) && new Set(value).size === value.length,
+};
+
+// fieldOf reads a field's declaration in "emits" ("number", "text?"): its
+// kind and whether it may be left out; null for one the Chest refuses.
+export function fieldOf(declared: unknown): { kind: FieldKind; optional: boolean } | null {
+  if (typeof declared !== "string") return null;
+  const optional = declared.endsWith("?"), kind = optional ? declared.slice(0, -1) : declared;
+  return Object.hasOwn(kinds, kind) ? { kind: kind as FieldKind, optional } : null;
+}
+
+// isDeclaredData says data is what its type declares: an object with every
+// required field, no field not declared, each value of its kind — null is
+// a field left out. declared
+// maps each field to its kind ("text?"), as "emits" names them; known says
+// a member is one the publisher has or had. Its size (maxData) is checked
+// apart.
+export function isDeclaredData(data: unknown, declared: Record<string, string>, known: (id: string) => boolean): boolean {
+  if (data === null || typeof data !== "object" || Array.isArray(data)) return false;
+  const given = data as Record<string, unknown>;
+  for (const name of Object.keys(given)) if (!Object.hasOwn(declared, name)) return false;
+  return Object.entries(declared).every(([name, spec]) => {
+    const field = fieldOf(spec);
+    if (!field) return false;
+    if (!Object.hasOwn(given, name) || given[name] === null) return field.optional;
+    return kinds[field.kind](given[name], known);
+  });
+}
+
+// An event's audience as the publisher names it: members, groups and roles
+// of the publisher, any of whom may see the item.
+export type Audience = { members?: string[]; groups?: string[]; roles?: string[] };
+const audienceLists: Record<keyof Audience, RegExp> = { members: memberIdPattern, groups: groupIdPattern, roles: rolePattern };
+
+// isAudience says a value is an audience the Chest takes: an object of
+// members, groups and roles only, each a list of distinct identifiers of
+// its grammar, one list at least not empty.
+export function isAudience(value: unknown): value is Audience {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const lists = Object.entries(value as Record<string, unknown>);
+  return lists.some(([, list]) => Array.isArray(list) && list.length > 0) && lists.every(([name, list]) =>
+    Object.hasOwn(audienceLists, name) && Array.isArray(list) && list.every(v => typeof v === "string" && audienceLists[name as keyof Audience].test(v)) && new Set(list).size === list.length);
+}

package/client/src/events.ts

@@ -1,14 +1,23 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 import type { IncomingMessage } from "node:http";
-import { ask, refusal } from "./api.js";
-import { ChestError, Unavailable } from "./errors.js";
+import { ask, json as readJson, refusal } from "./api.js";
+import { ChestError, TooLarge, Unavailable } from "./errors.js";
+import { clockSkew, eventWindow, instantOf, isAudience, isToolEventType, itemIdPattern, maxData, toolNamePattern, type Audience } from "./eventrules.js";
 import { memberIdPattern } from "./member.js";
 import { forget } from "./members.js";
 import { delivery, eventChannel, instant, json, memorySeen, object, type Seen } from "./signed.js";
 
-// What the Chest tells a server tool of its members' lifecycle, for a tool
-// whose chest.json declares "capabilities": ["members"] and "receives":
-// ["member.*"]. The Chest posts each event to the tool's POST /chest-events,
-// through its launcher only (never from the Internet), signed for this tool:
+// What the Chest tells a server tool, and what the tool tells other tools
+// of its Chest, on one route. Two kinds of events come to the tool's POST
+// /chest-events, through its launcher only (never from the Internet),
+// signed for this tool:
+//
+// - its members' lifecycle (member.updated, access.revoked, member.removed,
+//   member.erased), for a tool whose chest.json declares "capabilities":
+//   ["members"] and "receives": ["member.*"];
+// - events between tools: those another tool of the Chest emits
+//   ("quote.accepted"), for a tool whose chest.json "receives" names their
+//   type, once the owner approved the link between the two tools.
 //
 //   // app/chest-events/route.ts (Next.js): outside /chest, never behind a session
 //   import * as events from "@argentic/chest-sdk/events";
@@ -16,15 +25,23 @@ import { delivery, eventChannel, instant, json, memorySeen, object, type Seen }
 //     return new Response(null, { status: await events.handle(request, {
 //       "member.erased": async e => { await anonymise(e.data.id); await events.acknowledgeErasure(e.data.erasure); },
 //       "access.revoked": e => unassign(e.data.id),
+//       "quote.accepted": e => createProject(e.data, e.audience),
 //     }, { seen }) });
 //   }
 //
-// Delivery is at least once, in no guaranteed order: the same event may come
-// again, always with the same id — handle() drops what the store of seen ids
-// already holds. An event the tool does not answer with a success is
-// delivered again, after a growing delay, for 72 hours; after that the tool
-// is out of sync and reconciles by listing its members (members.list) at its
-// next start. Every event also empties what members.lookup keeps.
+// A tool tells the others with emit, for the types its chest.json declares
+// in "emits", each with the fields its data carries:
+//
+//   await events.emit("quote.accepted", { quote: q.id, total: q.total }, { subject: q.id, key: `accepted:${q.id}` });
+//
+// Delivery is at least once: the same event may come again, always with the
+// same id — handle() drops what the store of seen ids already holds. Tool
+// events of one subject come in the order emitted; nothing else is ordered.
+// An event the tool does not answer with a success is delivered again,
+// after a growing delay, for 72 hours; after that a member event leaves the
+// tool out of sync (it reconciles by listing its members, members.list, at
+// its next start) and a tool event is kept as a failed delivery an admin
+// may send again. Every member event also empties what members.lookup keeps.
 
 // What changed of a member the tool sees; "email" only with members.email;
 // "language" and "timeZone": the language the Chest speaks to them and the
@@ -39,12 +56,32 @@ export type MemberRemoved = { id: string; type: "member.removed"; occurredAt: st
 // The owner asked for this person's data to be erased: delete or anonymise
 // what the tool keeps of them before deadline, then acknowledgeErasure(erasure).
 export type MemberErased = { id: string; type: "member.erased"; occurredAt: string; data: { id: string; erasure: string; deadline: string } };
-// An event, told apart by its type.
+// An event of the members' lifecycle, told apart by its type.
 export type ChestEvent = MemberUpdated | AccessRevoked | MemberRemoved | MemberErased;
 export type ChestEventType = ChestEvent["type"];
 
-// What handle() calls for each type; a type left out is accepted and ignored.
-export type Handlers = { [K in ChestEventType]?: (event: Extract<ChestEvent, { type: K }>) => void | Promise<void> };
+// An event another tool of the Chest told (emit): its id ("evt_…", the same
+// on every delivery of it), its type, the tool that told it (source, stamped
+// by the Chest), when it happened, the thing it is about (subject, when the
+// publisher named one), who may see it, and its data — the fields its type
+// declares in the publisher's chest.json, member ids for people. audience is
+// "all" when every member who has this tool may see the item, otherwise
+// the members of this tool who may: show it to them only (the Chest never
+// delivers an item none of them may see; honouring the list is the tool's
+// rule). Read data defensively: a publisher's later version may add fields.
+export type ToolEvent = { id: string; type: string; source: string; occurredAt: string; subject?: string; audience: "all" | string[]; data: Record<string, unknown> };
+// What a delivery carries: an event of the members' lifecycle, or of a tool.
+export type ReceivedEvent = ChestEvent | ToolEvent;
+
+// The type of an event between tools as a handler is keyed: dotted words.
+export type ToolEventType = `${string}.${string}`;
+// What handle() calls for an event of type K: the event of the members'
+// lifecycle of that type, or a tool event.
+export type Handler<K extends string> = (event: K extends ChestEventType ? Extract<ChestEvent, { type: K }> : ToolEvent) => void | Promise<void>;
+// What handle() calls for each type — a member type ("access.revoked"),
+// given its own event, or a type of another tool ("quote.accepted"), given a
+// ToolEvent; a type left out is accepted and ignored.
+export type Handlers<K extends ToolEventType = ChestEventType | ToolEventType> = { [P in K]?: Handler<P> };
 
 // Where handle() remembers the ids of the events already handled (Seen), and
 // memorySeen, which keeps them in this process: shared with schedules.
@@ -54,19 +91,15 @@ export { memorySeen, type Seen } from "./signed.js";
 export const erasureIdPattern = /^era_[a-z2-7]{26}$/u;
 const changes: readonly string[] = ["name", "photo", "role", "groups", "email", "language", "timeZone"];
 
-// envelope reads a signed delivery: the envelope when the signature, the tool,
-// the time and the digest of the body hold; known says its type is one this
-// SDK reads.
-async function envelope(request: IncomingMessage | Request): Promise<{ event: ChestEvent; known: true } | { event: { id: string }; known: false } | null> {
-  const signed = await delivery(request, eventChannel);
-  if (!signed) return null;
-  const { id: jti, body } = signed;
-  const e = object(json(body.toString("utf8")));
-  if (!e || Object.keys(e).length !== 4 || e["id"] !== jti || typeof e["type"] !== "string" || !instant(e["occurredAt"])) return null;
+// memberEvent reads the envelope of a member event (its four keys): the
+// event when it is one this SDK reads, known false for a type of a later
+// Chest, null for one its type cannot say.
+function memberEvent(e: Record<string, unknown>, id: string): { event: ChestEvent; known: true } | { known: false } | null {
+  if (Object.keys(e).length !== 4 || typeof e["type"] !== "string" || !instant(e["occurredAt"])) return null;
   const data = object(e["data"]);
   if (!data || typeof data["id"] !== "string" || !memberIdPattern.test(data["id"])) return null;
   const keys = Object.keys(data).sort().join(",");
-  const base = { id: jti, occurredAt: e["occurredAt"] as string };
+  const base = { id, occurredAt: e["occurredAt"] as string };
   switch (e["type"]) {
     case "member.updated": {
       const changed = data["changed"];
@@ -81,43 +114,152 @@ async function envelope(request: IncomingMessage | Request): Promise<{ event: Ch
       return { known: true, event: { ...base, type: "member.erased", data: { id: data["id"], erasure: data["erasure"], deadline: data["deadline"] as string } } };
   }
   // A type of a later Chest: signed, so the tool accepts it, and ignores it.
-  return { known: false, event: { id: jti } };
+  return { known: false };
+}
+
+const toolKeys = new Set(["id", "type", "source", "occurredAt", "subject", "audience", "data"]);
+// toolEvent reads the envelope of a tool event: its keys exactly, subject
+// only when the publisher named one; null for anything else.
+function toolEvent(e: Record<string, unknown>, id: string): ToolEvent | null {
+  const { type, source, occurredAt, subject, audience } = e, data = object(e["data"]);
+  if (Object.keys(e).length !== toolKeys.size - (subject === undefined ? 1 : 0) || !Object.keys(e).every(k => toolKeys.has(k))) return null;
+  if (!isToolEventType(type) || typeof source !== "string" || !toolNamePattern.test(source) || instantOf(occurredAt) === null || !data) return null;
+  if (subject !== undefined && (typeof subject !== "string" || !itemIdPattern.test(subject))) return null;
+  const all = audience === "all";
+  if (!all && (!Array.isArray(audience) || audience.length === 0 || !audience.every(m => typeof m === "string" && memberIdPattern.test(m)) || new Set(audience).size !== audience.length)) return null;
+  return { id, type, source, occurredAt: occurredAt as string, ...(subject === undefined ? {} : { subject }), audience: all ? "all" : [...audience as string[]], data };
+}
+
+// envelope reads a signed delivery: the event when the signature, the tool,
+// the time and the digest of the body hold and the envelope is one of a
+// member event or of a tool event (it carries a source); known false for a
+// member event of a type this SDK does not read.
+async function envelope(request: IncomingMessage | Request): Promise<{ event: ReceivedEvent; known: true } | { known: false } | null> {
+  const signed = await delivery(request, eventChannel);
+  if (!signed) return null;
+  const e = object(json(signed.body.toString("utf8")));
+  if (!e || e["id"] !== signed.id) return null;
+  if (!Object.hasOwn(e, "source")) return memberEvent(e, signed.id);
+  const event = toolEvent(e, signed.id);
+  return event ? { known: true, event } : null;
 }
 
 // verify returns the event a delivery carries, or null when it is not one
 // the Chest made for this tool — no or another signature, for another tool,
-// expired, a body that is not the one signed, not a POST — or when it is of a
-// type this SDK does not know. It reads the body (64 KiB at most): call it
-// before anything else reads it. It never throws for what a request carries.
-export async function verify(request: IncomingMessage | Request): Promise<ChestEvent | null> {
+// expired, a body that is not the one signed, not a POST — or when it is a
+// member event of a type this SDK does not know. It reads the body (32 MiB
+// at most, once its signature holds: a tool event names who may see it,
+// up to a whole team): call it before anything else reads it. It never
+// throws for what a request carries.
+export async function verify(request: IncomingMessage | Request): Promise<ReceivedEvent | null> {
   const read = await envelope(request);
   return read?.known ? read.event : null;
 }
 
 const remembered = memorySeen();
+// The event whose handler runs: an emit made while it runs continues its
+// chain (cause), so that the Chest cuts a loop between tools.
+const handling = new AsyncLocalStorage<string>();
 
 // handle verifies one delivery and hands the event to its handler, once:
 // the status to answer the Chest. 401 for a delivery that is not the
 // Chest's; 204 for an event handled, one already seen (seen.has), a type
-// without a handler or one this SDK does not know. A handler that throws
-// leaves the event unseen and handle throws: answer 500, the Chest delivers
-// it again. seen is the store of the ids handled (memorySeen by default,
-// lost at a restart: give a durable one).
-export async function handle(request: IncomingMessage | Request, handlers: Handlers, options: { seen?: Seen } = {}): Promise<number> {
+// without a handler or a member type this SDK does not know. A handler that
+// throws leaves the event unseen and handle throws: answer 500, the Chest
+// delivers it again. seen is the store of the ids handled (memorySeen by
+// default, lost at a restart: give a durable one). An emit made by the
+// handler of a tool event carries that event as its cause, by itself.
+export async function handle<K extends ToolEventType>(request: IncomingMessage | Request, handlers: Handlers<K>, options: { seen?: Seen } = {}): Promise<number> {
   const read = await envelope(request);
   if (!read) return 401;
   if (!read.known) return 204;
   const seen = options.seen ?? remembered;
   const event = read.event;
   if (await seen.has(event.id)) return 204;
-  // A member changed or left: what lookup kept of them is stale.
-  forget();
-  const handler = handlers[event.type] as ((e: ChestEvent) => void | Promise<void>) | undefined;
-  if (handler) await handler(event);
+  const handler = Object.hasOwn(handlers, event.type) ? (handlers as Record<string, ((e: ReceivedEvent) => void | Promise<void>) | undefined>)[event.type] : undefined;
+  if ("source" in event) {
+    if (handler) await handling.run(event.id, () => handler(event));
+  } else {
+    // A member changed or left: what lookup kept of them is stale.
+    forget();
+    if (handler) await handler(event);
+  }
   await seen.add(event.id);
   return 204;
 }
 
+// Who, in the tool, may see the item an event is about: some of its
+// members, the members of some groups, the members holding some of its
+// roles (chest.json "roles"); left out, everyone who has the tool.
+export type EmitAudience = Audience;
+// What an emit may say besides its type and data: the thing it is about
+// (subject, an identifier of the tool's own: a receiver gets one subject's
+// events in the order emitted), an idempotency key (the same key within 72
+// hours answers the same event, told once), when it happened (now by
+// default; within the last 72 hours), and its audience.
+export type EmitOptions = { subject?: string; key?: string; occurredAt?: Date | string; audience?: EmitAudience };
+// What the Chest answers an emit: the event's id, and how many tools it was
+// written for (0 is no error: no installed tool listens, or none of their
+// members may see it).
+export type Emitted = { id: string; receivers: number };
+
+// audienceOf is the audience as the Chest takes it: each list once per
+// identifier, empty lists left out; invalid_audience when it names nobody
+// or an identifier of no grammar.
+function audienceOf(given: EmitAudience): Audience {
+  const audience = object(given) && Object.fromEntries(Object.entries(given).filter(([, list]) => !Array.isArray(list) || list.length > 0).map(([name, list]) => [name, Array.isArray(list) ? [...new Set(list)] : list]));
+  if (!isAudience(audience)) throw new ChestError("invalid_audience", 400, "an audience names members (mbr_…), groups (grp_…) or roles of the tool, one at least");
+  return audience;
+}
+
+// emit tells the tools of the Chest that receive its type that something
+// happened in this tool: type is one its chest.json declares in "emits",
+// data its declared fields (16 KiB of JSON at most). The Chest writes it
+// for each linked receiver before answering, and delivers it at least once.
+// Emitted from a handler of a tool event, it continues that event's chain
+// by itself (the Chest tells nobody an event that would loop). Errors:
+// ChestError invalid_type (400: not declared in "emits", or not a type),
+// invalid_data (400: a field not declared, missing or of another kind, a
+// member the tool never had), invalid_audience (400), invalid_event (400:
+// subject, key or occurredAt), key_reused (409: the key went with other
+// content); TooLarge (413), CapabilityNotGranted (403: the version emits
+// nothing), Unavailable (the event may or may not be told: emit again with
+// the same key).
+export async function emit(type: string, data: Record<string, unknown>, options: EmitOptions = {}): Promise<Emitted> {
+  if (!isToolEventType(type)) throw new ChestError("invalid_type", 400, "a type is two to four dotted lowercase words (quote.accepted), not member.* nor access.*");
+  if (!object(data)) throw new ChestError("invalid_data", 400, "data is an object of the fields the type declares");
+  let size: number;
+  try {
+    size = Buffer.byteLength(JSON.stringify(data));
+  } catch {
+    throw new ChestError("invalid_data", 400, "data is not JSON");
+  }
+  if (size > maxData) throw new TooLarge();
+  const { subject, key, occurredAt, audience } = options;
+  for (const id of [subject, key]) {
+    if (id !== undefined && (typeof id !== "string" || !itemIdPattern.test(id))) throw new ChestError("invalid_event", 400, "a subject or a key is 1 to 128 letters, digits and . _ : -, starting with a letter or a digit");
+  }
+  const at = occurredAt instanceof Date ? (Number.isNaN(occurredAt.getTime()) ? undefined : occurredAt.toISOString()) : occurredAt;
+  if (occurredAt !== undefined) {
+    const time = instantOf(at), now = Date.now();
+    if (time === null || time > now + clockSkew || time < now - eventWindow) throw new ChestError("invalid_event", 400, "occurredAt is an RFC 3339 instant of the last 72 hours");
+  }
+  const cause = handling.getStore();
+  const body = JSON.stringify({ type, data, ...(subject === undefined ? {} : { subject }), ...(key === undefined ? {} : { key }), ...(at === undefined ? {} : { occurredAt: at }), ...(audience === undefined ? {} : { audience: audienceOf(audience) }), ...(cause === undefined ? {} : { cause }) });
+  const response = await ask("events", "POST", "/events", { body, type: "application/json" });
+  if (response.status === 200 || response.status === 202) {
+    const answer = object(await readJson(response));
+    const id = answer?.["id"], receivers = answer?.["receivers"];
+    if (typeof id !== "string" || !eventChannel.id.test(id) || typeof receivers !== "number" || !Number.isSafeInteger(receivers) || receivers < 0) throw new Unavailable();
+    return { id, receivers };
+  }
+  if (response.status < 400) {
+    await response.body?.cancel();
+    throw new Unavailable();
+  }
+  throw await refusal(response, "events");
+}
+
 // acknowledgeErasure tells the Chest the tool deleted or anonymised what it
 // kept of the person of that erasure (member.erased): the owner sees it done.
 // Acknowledging again is harmless. Errors: ChestError erasure_not_found