@argentic/chest-sdk 0.4.1 → 0.5.0

package/dist/src/testing.js

@@ -1,8 +1,10 @@
-import { createHash, randomBytes } from "node:crypto";
+import { createCipheriv, createDecipheriv, createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import { createServer } from "node:http";
-import { groupIdPattern, memberIdPattern } from "./member.js";
+import { clockSkew, eventWindow, fieldNamePattern, fieldOf, instantOf, isAudience, isDeclaredData, isToolEventType, itemIdPattern, maxData, rolePattern } from "./eventrules.js";
+import { groupIdPattern, languagePattern, memberIdPattern } from "./member.js";
 import { forget } from "./members.js";
-import { eventChannel, scheduleChannel, sign, signClaims } from "./signed.js";
+import { eventChannel, json, object, scheduleChannel, sign, signClaims } from "./signed.js";
+import { fakeRealtime } from "./testing-realtime.js";
 // signAssertion is the Chest-Member value the Chest's front would send for
 // that member: HS256 under the key of the token, for the tool, valid 60
 // seconds from when it is issued.
@@ -11,7 +13,7 @@ export function signAssertion(member, options = {}) {
     const tool = options.tool ?? process.env["CHEST_TOOL"];
     if (!token || !tool)
         throw new Error("signAssertion needs a token and a tool: start a fakeChest, or name them");
-    if (!memberIdPattern.test(member.id) || !member.groups.every(g => groupIdPattern.test(g)))
+    if (!memberIdPattern.test(member.id) || !(member.groups ?? []).every(g => groupIdPattern.test(g)))
         throw new Error("signAssertion needs identifiers of the Chest's shape (mbr_…, grp_…)");
     const iat = Math.floor((options.now ?? new Date()).getTime() / 1000);
     // Under the label of the assertion's shape, as the Chest signs it and
@@ -19,21 +21,31 @@ export function signAssertion(member, options = {}) {
     return signClaims("Chest-Member v2", {
         iss: `https://${tool}-chest.chest.test`, aud: tool, iat, exp: iat + 60, sub: member.id,
         given_name: member.firstName, family_name: member.lastName, name: member.name, picture: member.photo ?? "", role: member.role ?? "",
-        admin: member.isAdmin, builder: member.isBuilder, groups: member.groups, time_zone: member.timeZone, ...(member.email === undefined ? {} : { email: member.email }),
+        admin: member.isAdmin, builder: member.isBuilder, ...(member.groups === null ? { groups_overage: true } : { groups: member.groups }), time_zone: member.timeZone, ...(member.email === undefined ? {} : { email: member.email }),
         language: member.language,
     }, token);
 }
+// ticketOf makes the ticket of a member's request to open sealed values
+// (Chest-Opener), under the key of the fake Chest running; null when none
+// runs. The tool never holds that key: only the Chest makes tickets.
+let ticketOf = null;
 // withMember is the request carrying that member's assertion, signed with
-// the options of signAssertion: a new Web Request, or the same Node request
-// with its header set.
+// the options of signAssertion, and — while a fake Chest runs — the
+// member's ticket to open sealed values: a new Web Request, or the same
+// Node request with its headers set.
 export function withMember(request, member, options = {}) {
     const assertion = signAssertion(member, options);
+    const ticket = ticketOf?.(member.id);
     if (request instanceof Request) {
         const headers = new Headers(request.headers);
         headers.set("Chest-Member", assertion);
+        if (ticket)
+            headers.set("Chest-Opener", ticket);
         return new Request(request, { headers });
     }
     request.headers["chest-member"] = assertion;
+    if (ticket)
+        request.headers["chest-opener"] = ticket;
     return request;
 }
 // The bounds of a Chest (chest/toolmembers, chest/toolfiles).
@@ -41,21 +53,54 @@ const maxLimit = 500, defaultLimit = 100, maxLookup = 200, callsPerMinute = 600;
 const maxObject = 32 << 20, maxObjects = 10000, maxTotal = 1 << 30;
 const namePattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}(\/[A-Za-z0-9][A-Za-z0-9._-]{0,99}){0,7}$/u;
 // Its links and uploads: their paths on the team host, their lives in
-// seconds, the images it makes thumbnails of, the first bytes an upload of
-// a type must start with, the endings of the names it chooses (chest/toolfiles).
+// seconds, the images it makes thumbnails of, the types it recognises by
+// their content — a member's upload of one must hold it, a visitor's is of
+// the one its content is —, the endings of the names it chooses
+// (chest/toolfiles). An office document is told by the names of its parts,
+// read in its bytes rather than in its archive's directory.
 const linkPath = "/_chest/files/", uploadPath = "/_chest/files/upload/", linkLife = 900, uploadLife = 900;
 const mediaPattern = /^[a-z0-9][a-z0-9!#$&^_.+-]{0,62}\/(\*|[a-z0-9][a-z0-9!#$&^_.+-]{0,62})$/u;
 const thumbnailed = ["image/jpeg", "image/png", "image/gif", "image/webp"];
 const starts = (...heads) => (data) => heads.some(head => data.subarray(0, head.length).equals(Buffer.from(head, "latin1")));
-const signatures = {
+const text = (data, from, to) => data.subarray(from, to).toString("latin1");
+const brands = (...said) => (data) => text(data, 4, 8) === "ftyp" && Array.from({ length: Math.max(0, Math.min(data.readUInt32BE(0), data.length) - 8) / 4 }, (_, i) => text(data, 8 + 4 * i, 12 + 4 * i)).some((brand, i) => i !== 1 && said.includes(brand));
+const zip = starts("PK\x03\x04", "PK\x05\x06");
+const office = (main) => (data) => zip(data) && data.includes("[Content_Types].xml") && data.includes(main);
+const openDocument = (type) => (data) => zip(data) && text(data, 30, 38) === "mimetype" && text(data, 38, 38 + type.length) === type;
+const recognisers = {
     "image/jpeg": starts("\xff\xd8\xff"), "image/png": starts("\x89PNG\r\n\x1a\n"), "image/gif": starts("GIF87a", "GIF89a"),
-    "image/webp": data => data.subarray(0, 4).toString("latin1") === "RIFF" && data.subarray(8, 12).toString("latin1") === "WEBP", "application/pdf": starts("%PDF-"),
+    "image/webp": data => text(data, 0, 4) === "RIFF" && text(data, 8, 12) === "WEBP", "image/avif": brands("avif", "avis"), "image/heic": brands("heic", "heix", "heim", "heis", "hevc", "hevx"),
+    "image/bmp": starts("BM"), "image/tiff": starts("II*\x00", "MM\x00*"), "application/pdf": starts("%PDF-"),
+    "application/zip": zip, "application/gzip": starts("\x1f\x8b"), "application/x-7z-compressed": starts("7z\xbc\xaf\x27\x1c"), "application/vnd.rar": starts("Rar!\x1a\x07"),
+    "application/x-tar": data => text(data, 257, 262) === "ustar", "application/x-bzip2": starts("BZh"), "application/x-xz": starts("\xfd7zXZ\x00"), "application/vnd.ms-cab-compressed": starts("MSCF"),
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document": office("word/document.xml"),
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": office("xl/workbook.xml"),
+    "application/vnd.openxmlformats-officedocument.presentationml.presentation": office("ppt/presentation.xml"),
+    "application/vnd.oasis.opendocument.text": openDocument("application/vnd.oasis.opendocument.text"),
+    "application/vnd.oasis.opendocument.spreadsheet": openDocument("application/vnd.oasis.opendocument.spreadsheet"),
+    "application/vnd.oasis.opendocument.presentation": openDocument("application/vnd.oasis.opendocument.presentation"),
+};
+// The types recognised, an office document before the archive it also is.
+const precise = (type) => type.includes("officedocument") || type.includes("opendocument");
+const recognised = Object.keys(recognisers).sort((a, b) => Number(precise(b)) - Number(precise(a)) || (a < b ? -1 : a > b ? 1 : 0));
+const accepted = (types, type) => types.some(t => t === type || (t.endsWith("/*") && type.startsWith(t.slice(0, -1))));
+const extensions = {
+    "image/jpeg": ".jpg", "image/png": ".png", "image/gif": ".gif", "image/webp": ".webp", "image/avif": ".avif", "image/heic": ".heic", "image/bmp": ".bmp", "image/tiff": ".tiff",
+    "application/pdf": ".pdf", "text/plain": ".txt", "text/csv": ".csv", "application/json": ".json", "application/zip": ".zip",
+    "application/gzip": ".gz", "application/x-7z-compressed": ".7z", "application/vnd.rar": ".rar", "application/x-tar": ".tar", "application/x-bzip2": ".bz2", "application/x-xz": ".xz", "application/vnd.ms-cab-compressed": ".cab",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document": ".docx", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": ".xlsx",
+    "application/vnd.openxmlformats-officedocument.presentationml.presentation": ".pptx", "application/vnd.oasis.opendocument.text": ".odt",
+    "application/vnd.oasis.opendocument.spreadsheet": ".ods", "application/vnd.oasis.opendocument.presentation": ".odp", "video/mp4": ".mp4", "audio/mpeg": ".mp3",
 };
-const extensions = { "image/jpeg": ".jpg", "image/png": ".png", "image/gif": ".gif", "image/webp": ".webp", "image/avif": ".avif", "image/heic": ".heic", "application/pdf": ".pdf", "text/plain": ".txt", "text/csv": ".csv", "application/json": ".json", "application/zip": ".zip", "video/mp4": ".mp4", "audio/mpeg": ".mp3" };
 const newToken = () => randomBytes(18).toString("base64url") + "." + randomBytes(12).toString("base64url");
 // Its notifications: recipients and badges a call, text, quotas.
-const maxRecipients = 500, maxTitle = 80, maxText = 280, maxPath = 512, maxCount = 9999;
-const recipientsPerHour = 1000, itemsPerDay = 100, badgesPerMinute = 600;
+// No count bounds a call but the team's size: a body takes the texts and an
+// entry for each member who has the tool. Nothing is refused for its pace:
+// ten items at once to a member, one more every six minutes; beyond, the
+// notices are folded into the one grouped item of that member.
+const maxTitle = 80, maxText = 280, maxPath = 512, maxCount = 9999, maxRoles = 16;
+const textBytes = 64 << 10, memberBytes = 64;
+const paceBurst = 10, paceEvery = 6 * 60_000;
 const keyPattern = /^[a-z0-9._:-]{1,64}$/u;
 const reordering = /[\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/gu;
 const cleanTitle = (s) => s.replace(/[\t\r\n]/gu, " ").replace(/\p{Cc}/gu, "").replace(reordering, "").trim();
@@ -77,6 +122,19 @@ function vectorOf(text, dimensions) {
     const kept = values.slice(0, dimensions), norm = Math.hypot(...kept) || 1;
     return kept.map(x => x / norm);
 }
+// Its sealed values: a call's body, one value, a context, a ticket's life
+// in seconds (chest/toolseal).
+const sealedBody = 4 << 20, sealedValue = 512 << 10, sealedContext = 256, ticketLife = 60;
+const sealedText = /^chest:sealed:1:((?:[a-z][a-z0-9-]{0,47}(?:,[a-z][a-z0-9-]{0,47}){0,15})?):([A-Za-z0-9_-]+)$/u;
+// Its events: the keys of an emit, and its envelope beyond the data and
+// the identifiers of its audience.
+const emitKeys = ["type", "data", "subject", "key", "occurredAt", "audience", "cause"], envelopeBytes = 4096, idBytes = 64;
+// canonical is a value's JSON with the keys of each object in order: the
+// content an idempotency key stands for, whatever order the tool wrote.
+const canonical = (value) => Array.isArray(value) ? `[${value.map(canonical).join(",")}]`
+    : value !== null && typeof value === "object" ? `{${Object.keys(value).sort().map(k => JSON.stringify(k) + ":" + canonical(value[k])).join(",")}}`
+        : JSON.stringify(value) ?? "null";
+const newId = (prefix) => prefix + Array.from(randomBytes(26), b => "abcdefghijklmnopqrstuvwxyz234567"[b & 31]).join("");
 const fold = (s) => s.normalize("NFD").replace(/\p{Mn}/gu, "").toLowerCase();
 function send(response, status, value, headers = {}) {
     if (value === undefined)
@@ -102,7 +160,7 @@ async function body(request, limit) {
 // chest and the modules of the SDK read is then this Chest's.
 export async function fakeChest(options = {}) {
     const capabilities = new Set(options.capabilities ?? ["members", "files", "notifications", "ai"]);
-    const email = capabilities.has("members.email");
+    const email = capabilities.has("members.email"), everyGroup = capabilities.has("members.groups");
     const tool = process.env["CHEST_TOOL"] || "tool";
     const token = randomBytes(32).toString("base64url");
     const files = new Map();
@@ -110,12 +168,29 @@ export async function fakeChest(options = {}) {
         files.set(name, { data: typeof file.data === "string" ? new TextEncoder().encode(file.data) : file.data, type: file.type ?? "application/octet-stream", updated: new Date().toISOString() });
     }
     const receives = options.receives ?? ["member.*"];
-    // The erasures the tool was told of, by emit: those it may acknowledge.
+    // What the tool's chest.json declares it emits, refused as the Chest
+    // refuses the manifest.
+    const emits = options.emits ?? {};
+    for (const [type, declared] of Object.entries(emits)) {
+        const length = typeof declared?.description === "string" ? [...declared.description].length : 0;
+        if (!isToolEventType(type) || length < 1 || length > 80 || !object(declared.data) || !Object.entries(declared.data).every(([name, kind]) => fieldNamePattern.test(name) && fieldOf(kind) !== null)) {
+            throw new Error(`fakeChest: the Chest refuses "emits" ${JSON.stringify(type)}: a type of two to four dotted words, a description of 1 to 80 characters, camelCase fields of the kinds id, text, number, boolean, time, date, member, members (? when optional)`);
+        }
+    }
+    // The erasures the tool was told of, by deliver: those it may acknowledge.
     const erasures = new Set();
-    const chest = { api: "", token, tool, members: [...(options.members ?? [])], groups: [...(options.groups ?? [])], files, notifications: [], badges: new Map(), acknowledged: [], ai: [], emit: async () => 0, run: async () => 0, close: async () => { } };
+    const realtime = fakeRealtime(options.realtime ?? {}, () => chest.api, id => {
+        const m = chest.members.find(x => x.id === id);
+        return m ? m.role : undefined;
+    });
+    const chest = { api: "", token, tool, members: [...(options.members ?? [])], groups: [...(options.groups ?? [])], files, notifications: [], badges: new Map(), acknowledged: [], ai: [], opens: [], realtime: realtime.realtime, emitted: [], deliver: async () => 0, run: async () => 0, close: async () => { } };
     const former = [...(options.former ?? [])];
     let window = 0, calls = 0;
-    const shown = (m) => ({ id: m.id, first_name: m.firstName, last_name: m.lastName, name: m.name, photo: m.photo, role: m.role, admin: m.isAdmin, builder: m.isBuilder, groups: m.groups, language: m.language, time_zone: m.timeZone, ...(email && m.email !== undefined ? { email: m.email } : {}) });
+    // The groups the tool sees: those that give it, or all with members.groups;
+    // a member's groups among them (an identifier it was not given stays).
+    const unseen = () => new Set(everyGroup ? [] : chest.groups.filter(g => g.grants === false).map(g => g.id));
+    const groupsOf = (m) => (m.groups ?? []).filter(g => !unseen().has(g));
+    const shown = (m) => ({ id: m.id, first_name: m.firstName, last_name: m.lastName, name: m.name, photo: m.photo, role: m.role, admin: m.isAdmin, builder: m.isBuilder, groups: groupsOf(m), language: m.language, time_zone: m.timeZone, ...(email && m.email !== undefined ? { email: m.email } : {}) });
     const key = (m) => fold(m.name) + "\u0000" + m.id;
     const described = (name, f) => ({ name, type: f.type, size: f.data.byteLength, sha256: createHash("sha256").update(f.data).digest("hex"), updated: f.updated });
     async function members(request, response, url) {
@@ -136,7 +211,7 @@ export async function fakeChest(options = {}) {
             if (keys.some(k => !["after", "limit", "q", "role", "group"].includes(k) || q.getAll(k).length !== 1) || !Number.isInteger(limit) || limit < 1 || limit > maxLimit || String(limit) !== (q.get("limit") ?? String(defaultLimit)) || (group !== null && !groupIdPattern.test(group)) || search.length > 64)
                 return send(response, 400, { error: "invalid_query" });
             const shownList = chest.members
-                .filter(m => (role === null || m.role === role) && (group === null || m.groups.includes(group)) && (search === "" || [m.firstName, m.lastName, m.name, ...(email && m.email ? [m.email] : [])].some(n => fold(n).startsWith(search))))
+                .filter(m => (role === null || m.role === role) && (group === null || groupsOf(m).includes(group)) && (search === "" || [m.firstName, m.lastName, m.name, ...(email && m.email ? [m.email] : [])].some(n => fold(n).startsWith(search))))
                 .filter(m => after === "" || key(m) > after)
                 .sort((a, b) => key(a) < key(b) ? -1 : key(a) > key(b) ? 1 : 0);
             const page = shownList.slice(0, limit);
@@ -178,8 +253,17 @@ export async function fakeChest(options = {}) {
             const m = chest.members.find(x => x.id === id);
             return m ? send(response, 200, shown(m)) : send(response, 404, { error: "member_not_found" });
         }
-        if (request.method === "GET" && url.pathname === "/groups")
-            return send(response, 200, { groups: chest.groups });
+        if (request.method === "GET" && url.pathname === "/groups") {
+            const q = url.searchParams, keys = [...q.keys()];
+            const limit = q.has("limit") ? Number(q.get("limit")) : defaultLimit;
+            const after = q.has("after") ? Buffer.from(q.get("after"), "base64url").toString() : "";
+            if ((q.has("after") && !groupIdPattern.test(after.split("\u0000")[1] ?? "")) || keys.some(k => !["after", "limit"].includes(k) || q.getAll(k).length !== 1) || !Number.isInteger(limit) || limit < 1 || limit > maxLimit || String(limit) !== (q.get("limit") ?? String(defaultLimit)))
+                return send(response, 400, { error: "invalid_query" });
+            const groupKey = (g) => fold(g.name) + "\u0000" + g.id;
+            const listed = chest.groups.filter(g => !unseen().has(g.id) && (after === "" || groupKey(g) > after)).sort((a, b) => groupKey(a) < groupKey(b) ? -1 : groupKey(a) > groupKey(b) ? 1 : 0);
+            const page = listed.slice(0, limit);
+            return send(response, 200, { groups: page.map(g => ({ id: g.id, name: g.name, size: g.members.filter(access).length })), next: listed.length > limit ? Buffer.from(groupKey(page.at(-1))).toString("base64url") : null });
+        }
         send(response, 404, { error: "not_found" });
     }
     async function filesRoute(request, response, url) {
@@ -213,19 +297,23 @@ export async function fakeChest(options = {}) {
                 return send(response, 200, { url: `${chest.api}${linkPath}${token}`, expires_in: linkLife });
             }
             if (url.pathname === "/files/upload-url") {
-                const { name, max_size: maxSize, types, expires_in: expiresIn } = command;
+                const { name, max_size: maxSize, types, expires_in: expiresIn, public: visitor } = command;
                 const folder = typeof name === "string" && name.endsWith("/");
-                if (typeof name !== "string" || !namePattern.test(folder ? name.slice(0, -1) : name))
+                if (typeof name !== "string" || !namePattern.test(folder ? name.slice(0, -1) : name) || (visitor === true && !folder))
                     return send(response, 400, { error: "invalid_name" });
                 if (!(types === undefined || (Array.isArray(types) && types.length <= 8 && types.every(t => typeof t === "string" && mediaPattern.test(t)))))
                     return send(response, 400, { error: "invalid_type" });
-                if (!(maxSize === undefined || (typeof maxSize === "number" && Number.isSafeInteger(maxSize) && maxSize > 0)) || !(expiresIn === undefined || (typeof expiresIn === "number" && Number.isInteger(expiresIn) && expiresIn > 0 && expiresIn <= uploadLife)))
+                if (visitor === true && (!Array.isArray(types) || types.length === 0 || !types.every(t => recognised.some(r => accepted([t], r)))))
+                    return send(response, 400, { error: "invalid_type" });
+                if (!(maxSize === undefined || (typeof maxSize === "number" && Number.isSafeInteger(maxSize) && maxSize > 0)) || !(expiresIn === undefined || (typeof expiresIn === "number" && Number.isInteger(expiresIn) && expiresIn > 0 && expiresIn <= uploadLife)) || !(visitor === undefined || typeof visitor === "boolean"))
                     return send(response, 400, { error: "invalid_body" });
+                if (visitor === true && process.env["CHEST_PUBLIC_URL"] === undefined)
+                    return send(response, 409, { error: "no_public_part" });
                 if ((maxSize ?? 0) > maxObject)
                     return send(response, 413, { error: "too_large" });
                 const token = newToken(), life = expiresIn ?? uploadLife;
-                uploads.set(token, { name, maxSize: maxSize ?? maxObject, types: types ?? [], until: Date.now() + life * 1000 });
-                return send(response, 200, { url: `${chest.api}${uploadPath}${token}`, method: "PUT", expires_in: life });
+                uploads.set(token, { name, maxSize: maxSize ?? maxObject, types: types ?? [], until: Date.now() + life * 1000, visitor: visitor === true });
+                return send(response, 200, { url: visitor === true ? uploadPath + token : `${chest.api}${uploadPath}${token}`, method: "PUT", expires_in: life });
             }
             const from = command["from"], to = command["to"];
             if (typeof from !== "string" || typeof to !== "string" || !namePattern.test(from) || !namePattern.test(to))
@@ -264,12 +352,14 @@ export async function fakeChest(options = {}) {
         }
         send(response, 404, { error: "not_found" });
     }
-    // The team host's part of the files, on the fake's own origin: a link it
-    // signed opens the content it was signed for, for its life, as long as
-    // the file is that content — a thumbnail is the image itself, a fake does
-    // not reduce it —; an upload token takes one file, once, within its life,
-    // of the types it names and up to its size, whose first bytes are those of
-    // its type, named by the Chest in a folder. Nobody's session is checked:
+    // The team host's and the public part's files, on the fake's own origin:
+    // a link it signed opens the content it was signed for, for its life, as
+    // long as the file is that content — a thumbnail is the image itself, a
+    // fake does not reduce it —; an upload token takes one file, once, within
+    // its life, up to its size, named by the Chest in a folder: a member's of
+    // the types it names, holding the type it says when the fake recognises
+    // it; a visitor's of the type its content is among those it names,
+    // whatever it says. Nobody's session is checked, nor a visitor's pace:
     // the Chest's own front does that.
     const links = new Map();
     const uploads = new Map();
@@ -289,13 +379,19 @@ export async function fakeChest(options = {}) {
         uploads.delete(token);
         if (!grant || grant.until < Date.now())
             return send(response, 403, { error: "invalid_token" });
-        const type = (request.headers["content-type"] ?? "").split(";")[0].trim().toLowerCase();
-        if (!mediaPattern.test(type) || type.endsWith("/*") || (grant.types.length > 0 && !grant.types.some(t => t === type || (t.endsWith("/*") && type.startsWith(t.slice(0, -1))))))
+        let type = (request.headers["content-type"] ?? "").split(";")[0].trim().toLowerCase();
+        if (!grant.visitor && (!mediaPattern.test(type) || type.endsWith("/*") || (grant.types.length > 0 && !accepted(grant.types, type))))
             return send(response, 415, { error: "type_refused" });
         const data = await body(request, grant.maxSize);
         if (data === null)
             return send(response, 413, { error: "too_large" });
-        if (signatures[type] && !signatures[type](data))
+        if (grant.visitor) {
+            const found = recognised.find(r => accepted(grant.types, r) && recognisers[r](data));
+            if (found === undefined)
+                return send(response, 415, { error: "type_refused" });
+            type = found;
+        }
+        else if (recognisers[type] && !recognisers[type](data))
             return send(response, 400, { error: "type_mismatch" });
         const name = grant.name.endsWith("/") ? grant.name + randomBytes(10).toString("hex") + (extensions[type] ?? "") : grant.name;
         const total = [...files.entries()].reduce((sum, [n, f]) => n === name ? sum : sum + f.data.byteLength, 0);
@@ -304,7 +400,6 @@ export async function fakeChest(options = {}) {
         files.set(name, { data: new Uint8Array(data), type, updated: new Date().toISOString() });
         send(response, 201, { name, type, size: data.length });
     }
-    const hour = { start: 0, count: 0 }, minute = { start: 0, count: 0 }, days = new Map();
     const live = (w, span, now) => w !== undefined && w.count > 0 && now - w.start < span;
     const wait = (w, span, now) => ({ "Retry-After": String(Math.max(1, Math.ceil((w.start + span - now) / 1000))) });
     const count = (w, span, now, n) => {
@@ -312,6 +407,18 @@ export async function fakeChest(options = {}) {
             [w.start, w.count] = [now, 0];
         w.count += n;
     };
+    // The pace of each member: a token bucket, as of when it was last used.
+    const buckets = new Map();
+    const paced = (id, now) => {
+        const b = buckets.get(id) ?? { tokens: paceBurst, at: now };
+        b.tokens = Math.min(paceBurst, b.tokens + (now - b.at) / paceEvery);
+        b.at = now;
+        buckets.set(id, b);
+        if (b.tokens < 1)
+            return false;
+        b.tokens--;
+        return true;
+    };
     const access = (id) => chest.members.some(m => m.id === id);
     // drop removes kept notifications in place: a test may hold the list.
     const drop = (gone) => {
@@ -321,7 +428,7 @@ export async function fakeChest(options = {}) {
     };
     // recipients reads 1 to 500 member identifiers, each once.
     function recipients(value) {
-        if (!Array.isArray(value) || value.length < 1 || value.length > maxRecipients)
+        if (!Array.isArray(value) || value.length < 1)
             return { error: "invalid_body" };
         if (!value.every(v => typeof v === "string" && memberIdPattern.test(v)))
             return { error: "invalid_id" };
@@ -331,9 +438,9 @@ export async function fakeChest(options = {}) {
         if (!capabilities.has("notifications"))
             return send(response, 403, { error: "capability_not_granted" });
         const badge = request.method === "PUT" && url.pathname.startsWith("/badges/");
-        if (!badge && !(request.method === "PUT" && url.pathname === "/badges") && !(request.method === "POST" && (url.pathname === "/notifications" || url.pathname === "/notifications/withdraw")))
+        if (!badge && !(request.method === "PUT" && url.pathname === "/badges") && !(request.method === "POST" && ["/notifications", "/notifications/broadcast", "/notifications/withdraw"].includes(url.pathname)))
             return send(response, 404, { error: "not_found" });
-        const raw = await body(request, 64 << 10);
+        const raw = await body(request, textBytes + memberBytes * chest.members.length);
         let command = null;
         try {
             const value = JSON.parse(raw?.toString() ?? "");
@@ -357,7 +464,7 @@ export async function fakeChest(options = {}) {
             }
             else {
                 const list = command?.["badges"];
-                if (!keys("badges") || !Array.isArray(list) || list.length < 1 || list.length > maxRecipients || !list.every(b => b !== null && typeof b === "object" && !Array.isArray(b) && Object.keys(b).every(k => k === "member" || k === "count")))
+                if (!keys("badges") || !Array.isArray(list) || list.length < 1 || !list.every(b => b !== null && typeof b === "object" && !Array.isArray(b) && Object.keys(b).every(k => k === "member" || k === "count")))
                     return send(response, 400, { error: "invalid_body" });
                 writes = list;
                 if (!writes.every(b => typeof b.member === "string" && memberIdPattern.test(b.member)))
@@ -367,9 +474,6 @@ export async function fakeChest(options = {}) {
                 return send(response, 400, { error: "invalid_count" });
             if (new Set(writes.map(b => b.member)).size !== writes.length)
                 return send(response, 400, { error: "invalid_body" });
-            if (live(minute, 60_000, now) && minute.count + writes.length > badgesPerMinute)
-                return send(response, 429, { error: "quota_exceeded" }, wait(minute, 60_000, now));
-            count(minute, 60_000, now, writes.length);
             const answer = { set: [], skipped: [] };
             for (const b of writes) {
                 if (!access(b.member)) {
@@ -396,36 +500,78 @@ export async function fakeChest(options = {}) {
             drop(n => n.key === key && (named === null || named.includes(n.member)));
             return send(response, 204);
         }
-        if (!keys("members", "title", "body", "path", "key"))
+        const broadcast = url.pathname === "/notifications/broadcast";
+        if (!keys(broadcast ? "to" : "members", ...(broadcast ? ["except"] : []), "title", "body", "path", "key", "translations"))
             return send(response, 400, { error: "invalid_body" });
-        const { title, body: text, path, key } = command;
-        const ids = recipients(command["members"]);
-        if (!Array.isArray(ids))
-            return send(response, 400, ids);
-        if (typeof title !== "string" || [...title].length < 1 || [...title].length > maxTitle || cleanTitle(title) === "")
-            return send(response, 400, { error: "invalid_title" });
-        if (text !== undefined && (typeof text !== "string" || [...text].length > maxText))
-            return send(response, 400, { error: "invalid_text" });
+        let ids;
+        if (broadcast) {
+            const to = command["to"], except = command["except"];
+            if (to !== undefined && (to === null || typeof to !== "object" || Array.isArray(to) || !Object.keys(to).every(k => k === "groups" || k === "roles")))
+                return send(response, 400, { error: "invalid_body" });
+            const groups = to?.["groups"] ?? [], roles = to?.["roles"] ?? [];
+            if (!Array.isArray(groups) || !Array.isArray(roles) || (to !== undefined && groups.length + roles.length === 0) || roles.length > maxRoles || (except !== undefined && !Array.isArray(except)))
+                return send(response, 400, { error: "invalid_body" });
+            if (!groups.every(g => typeof g === "string" && groupIdPattern.test(g)) || !(except ?? []).every(id => typeof id === "string" && memberIdPattern.test(id)))
+                return send(response, 400, { error: "invalid_id" });
+            if (!roles.every(r => typeof r === "string" && rolePattern.test(r)))
+                return send(response, 400, { error: "invalid_role" });
+            ids = chest.members.filter(m => !(except ?? []).includes(m.id) && (to === undefined || (m.role !== null && roles.includes(m.role)) || groupsOf(m).some(g => groups.includes(g)))).map(m => m.id);
+        }
+        else {
+            const named = recipients(command["members"]);
+            if (!Array.isArray(named))
+                return send(response, 400, named);
+            ids = named;
+        }
+        const { path, key, translations } = command;
+        const words = (value) => {
+            const { title, body: text, ...rest } = (value ?? {});
+            if (value === null || typeof value !== "object" || Array.isArray(value) || Object.keys(rest).length > 0 || title === undefined)
+                return { error: "invalid_body" };
+            if (typeof title !== "string" || [...title].length < 1 || [...title].length > maxTitle || cleanTitle(title) === "")
+                return { error: "invalid_title" };
+            if (text !== undefined && (typeof text !== "string" || [...text].length > maxText))
+                return { error: "invalid_text" };
+            const cleaned = typeof text === "string" ? cleanText(text) : "";
+            return { title: cleanTitle(title), ...(cleaned ? { body: cleaned } : {}) };
+        };
+        const own = words({ title: command["title"], ...(command["body"] !== undefined ? { body: command["body"] } : {}) });
+        if ("error" in own)
+            return send(response, 400, own);
         if (path !== undefined && !isPath(path))
             return send(response, 400, { error: "invalid_path" });
         if (key !== undefined && (typeof key !== "string" || !keyPattern.test(key)))
             return send(response, 400, { error: "invalid_key" });
+        const other = new Map();
+        if (translations !== undefined) {
+            if (translations === null || typeof translations !== "object" || Array.isArray(translations))
+                return send(response, 400, { error: "invalid_body" });
+            for (const [language, value] of Object.entries(translations)) {
+                if (!languagePattern.test(language))
+                    return send(response, 400, { error: "invalid_language" });
+                const translated = words(value);
+                if ("error" in translated)
+                    return send(response, 400, translated);
+                other.set(language, translated);
+            }
+        }
         const kept = ids.filter(access);
-        if (live(hour, 3_600_000, now) && hour.count + kept.length > recipientsPerHour)
-            return send(response, 429, { error: "quota_exceeded" }, wait(hour, 3_600_000, now));
-        const full = kept.map(id => days.get(id)).filter((w) => live(w, 86_400_000, now) && w.count >= itemsPerDay);
-        if (full.length > 0)
-            return send(response, 429, { error: "quota_exceeded" }, wait(full.reduce((a, b) => a.start > b.start ? a : b), 86_400_000, now));
-        count(hour, 3_600_000, now, kept.length);
-        const cleaned = typeof text === "string" ? cleanText(text) : "";
         for (const id of kept) {
-            if (!days.has(id))
-                days.set(id, { start: 0, count: 0 });
-            count(days.get(id), 86_400_000, now, 1);
-            if (key !== undefined)
+            const language = chest.members.find(m => m.id === id).language;
+            const item = { member: id, ...(other.get(language) ?? own), path: path ?? "/chest", ...(key !== undefined ? { key: key } : {}) };
+            if (key !== undefined && chest.notifications.some(n => n.member === id && n.key === key))
                 drop(n => n.member === id && n.key === key);
-            chest.notifications.push({ member: id, title: cleanTitle(title), ...(cleaned ? { body: cleaned } : {}), path: path ?? "/chest", ...(key !== undefined ? { key: key } : {}) });
+            else if (!paced(id, now)) {
+                // Beyond the pace: folded into the member's grouped item, never refused.
+                const grouped = chest.notifications.find(n => n.member === id && n.grouped !== undefined);
+                drop(n => n === grouped);
+                delete item.key;
+                item.grouped = (grouped?.grouped ?? 0) + 1;
+            }
+            chest.notifications.push(item);
         }
+        if (broadcast)
+            return send(response, 204);
         send(response, 200, { delivered: kept, skipped: ids.filter(id => !access(id)) });
     }
     // Its AI: the declared aliases, the spending this month, the requests this
@@ -541,7 +687,83 @@ export async function fakeChest(options = {}) {
             response.write(part);
         response.end();
     }
-    // The acknowledgment of an erasure the tool was told of (emit).
+    // Its sealed values: AES-256-GCM under a key of its own — the format and
+    // the rules of a Chest, not its cipher —, bound to the tool, the roles
+    // and the context; its tickets, HMAC under another, for 60 seconds.
+    const sealingKey = randomBytes(32), ticketKey = randomBytes(32);
+    const additional = (roles, context) => Buffer.from(`chest:sealed:1:\u0000${tool}\u0000${roles}\u0000${context}`);
+    const ticketMac = (id, expiry) => createHmac("sha256", ticketKey).update(`${id}\u0000${expiry}`).digest();
+    ticketOf = id => { const expiry = String(Math.floor(Date.now() / 1000) + ticketLife); return `1.${id}.${expiry}.${ticketMac(id, expiry).toString("base64url")}`; };
+    const ticketMember = (ticket) => {
+        const parts = typeof ticket === "string" ? ticket.split(".") : [];
+        if (parts.length !== 4 || parts[0] !== "1" || !memberIdPattern.test(parts[1]) || Number(parts[2]) < Date.now() / 1000)
+            return null;
+        const mac = Buffer.from(parts[3], "base64url"), expected = ticketMac(parts[1], parts[2]);
+        return mac.length === expected.length && timingSafeEqual(mac, expected) ? parts[1] : null;
+    };
+    const isContext = (c) => c === undefined || (typeof c === "string" && Buffer.byteLength(c) <= sealedContext);
+    async function sealedRoute(request, response, url) {
+        if (!capabilities.has("sealed"))
+            return send(response, 403, { error: "capability_not_granted" });
+        if (request.method !== "POST" || url.search || (url.pathname !== "/sealed/seal" && url.pathname !== "/sealed/open"))
+            return send(response, 404, { error: "not_found" });
+        const id = url.pathname === "/sealed/open" ? ticketMember(request.headers["chest-opener"]) : null;
+        if (url.pathname === "/sealed/open" && id === null)
+            return send(response, 401, { error: "member_required" });
+        const raw = await body(request, sealedBody);
+        if (raw === null)
+            return send(response, 413, { error: "too_large" });
+        let items;
+        try {
+            items = JSON.parse(raw.toString()).items;
+        }
+        catch {
+            items = undefined;
+        }
+        if (!Array.isArray(items))
+            return send(response, 400, { error: "invalid_body" });
+        if (url.pathname === "/sealed/seal") {
+            const sealed = [];
+            for (const item of items) {
+                if (typeof item?.value !== "string" || Buffer.byteLength(item.value) > sealedValue || !isContext(item.context))
+                    return send(response, 400, { error: "invalid_body" });
+                const roles = item.roles;
+                if (roles !== undefined && (!Array.isArray(roles) || roles.length === 0 || roles.length > maxRoles || !roles.every(r => typeof r === "string" && rolePattern.test(r) && (!options.roles || options.roles.includes(r))) || new Set(roles).size !== roles.length))
+                    return send(response, 400, { error: "invalid_role" });
+                const joined = roles?.join(",") ?? "", nonce = randomBytes(12);
+                const cipher = createCipheriv("aes-256-gcm", sealingKey, nonce).setAAD(additional(joined, item.context ?? ""));
+                const box = Buffer.concat([nonce, cipher.update(item.value, "utf8"), cipher.final(), cipher.getAuthTag()]);
+                sealed.push(`chest:sealed:1:${joined}:${box.toString("base64url")}`);
+            }
+            return send(response, 200, { sealed });
+        }
+        const holder = chest.members.find(m => m.id === id);
+        if (!holder)
+            return send(response, 403, { error: "access_removed" });
+        const values = [];
+        for (const item of items) {
+            if (typeof item?.sealed !== "string" || !isContext(item.context))
+                return send(response, 400, { error: "invalid_body" });
+            const found = sealedText.exec(item.sealed), box = found ? Buffer.from(found[2], "base64url") : Buffer.alloc(0);
+            let value = null;
+            if (found && box.length >= 28) {
+                try {
+                    const decipher = createDecipheriv("aes-256-gcm", sealingKey, box.subarray(0, 12)).setAAD(additional(found[1], item.context ?? ""));
+                    decipher.setAuthTag(box.subarray(box.length - 16));
+                    value = Buffer.concat([decipher.update(box.subarray(12, box.length - 16)), decipher.final()]).toString("utf8");
+                }
+                catch {
+                    value = null;
+                }
+            }
+            const roles = found?.[1] ? found[1].split(",") : [];
+            values.push(value === null ? { refused: "invalid" } : roles.length && !roles.includes(holder.role ?? "") ? { refused: "role" } : { value });
+        }
+        if (values.length)
+            chest.opens.push({ member: holder.id, opened: values.filter(v => "value" in v).length, refused: values.filter(v => "refused" in v).length });
+        send(response, 200, { values });
+    }
+    // The acknowledgment of an erasure the tool was told of (deliver).
     async function erasuresRoute(request, response, url) {
         if (!receives.includes("member.*"))
             return send(response, 403, { error: "capability_not_granted" });
@@ -557,14 +779,70 @@ export async function fakeChest(options = {}) {
             chest.acknowledged.push(id);
         send(response, 204);
     }
+    // Realtime: the tool's API, and the probe of a page that asks whether its
+    // member may connect.
+    async function realtimeRoute(request, response, url) {
+        if (!capabilities.has("realtime"))
+            return send(response, url.pathname === "/_chest/realtime" ? 404 : 403, url.pathname === "/_chest/realtime" ? undefined : { error: "capability_not_granted" });
+        if (url.pathname === "/_chest/realtime")
+            return realtime.probe(response, url, send);
+        return realtime.api(request, response, url, body, send);
+    }
+    // The events the tool emits (POST /events), checked against its "emits"
+    // as the Chest checks them: a member it never had, a group it does not
+    // know, are refused; an idempotency key used within 72 hours answers its
+    // first event for the same content, key_reused for other content.
+    const used = new Map();
+    const had = (id) => access(id) || former.some(f => f.id === id);
+    async function eventsRoute(request, response, url) {
+        if (request.method !== "POST" || url.pathname !== "/events" || url.search)
+            return send(response, 404, { error: "not_found" });
+        if (Object.keys(emits).length === 0)
+            return send(response, 403, { error: "capability_not_granted" });
+        // The data, the envelope, and an audience of as many identifiers as the Chest holds.
+        const raw = await body(request, maxData + envelopeBytes + idBytes * (chest.members.length + former.length + chest.groups.length + maxRoles));
+        if (raw === null)
+            return send(response, 413, { error: "too_large" });
+        const command = object(json(raw.toString("utf8")));
+        if (!command || !Object.keys(command).every(k => emitKeys.includes(k)))
+            return send(response, 400, { error: "invalid_event" });
+        const { type, data, subject, key, occurredAt, audience, cause } = command;
+        if (!isToolEventType(type) || !Object.hasOwn(emits, type))
+            return send(response, 400, { error: "invalid_type" });
+        const now = Date.now(), time = occurredAt === undefined ? now : instantOf(occurredAt);
+        const identifier = (value, pattern) => value === undefined || (typeof value === "string" && pattern.test(value));
+        if (!identifier(subject, itemIdPattern) || !identifier(key, itemIdPattern) || !identifier(cause, eventChannel.id) || time === null || time > now + clockSkew || time < now - eventWindow)
+            return send(response, 400, { error: "invalid_event" });
+        if (Buffer.byteLength(JSON.stringify(data) ?? "") > maxData)
+            return send(response, 413, { error: "too_large" });
+        if (!isDeclaredData(data, emits[type].data, had))
+            return send(response, 400, { error: "invalid_data" });
+        if (audience !== undefined && (!isAudience(audience) || !(audience.members ?? []).every(had) || !(audience.groups ?? []).every(g => chest.groups.some(x => x.id === g))))
+            return send(response, 400, { error: "invalid_audience" });
+        const content = canonical({ type, data, subject, occurredAt, audience });
+        const first = key === undefined ? undefined : used.get(key);
+        if (first && now - first.at < eventWindow)
+            return first.content === content ? send(response, 200, { id: first.id, receivers: 0 }) : send(response, 409, { error: "key_reused" });
+        const id = newId("evt_");
+        if (key !== undefined)
+            used.set(key, { id, content, at: now });
+        chest.emitted.push({
+            id, type, data: data, ...(subject === undefined ? {} : { subject: subject }), ...(key === undefined ? {} : { key: key }),
+            occurredAt: occurredAt ?? new Date(now).toISOString(), ...(audience === undefined ? {} : { audience }), ...(cause === undefined ? {} : { cause: cause }),
+        });
+        send(response, 202, { id, receivers: 0 });
+    }
     const server = createServer((request, response) => {
         const url = new URL(request.url ?? "/", "http://127.0.0.1");
-        const route = url.pathname.startsWith("/_chest/files/") ? front
-            : url.pathname.startsWith("/erasures/") ? erasuresRoute
-                : url.pathname.startsWith("/ai/") ? aiRoute
-                    : url.pathname === "/members" || url.pathname.startsWith("/members/") || url.pathname === "/groups" ? members
-                        : url.pathname === "/files" || url.pathname.startsWith("/files/") ? filesRoute
-                            : url.pathname === "/badges" || url.pathname.startsWith("/badges/") || url.pathname.startsWith("/notifications") ? notificationsRoute : null;
+        const route = url.pathname === "/_chest/realtime" || url.pathname.startsWith("/realtime/") ? realtimeRoute
+            : url.pathname.startsWith("/_chest/files/") ? front
+                : url.pathname.startsWith("/erasures/") ? erasuresRoute
+                    : url.pathname === "/events" ? eventsRoute
+                        : url.pathname.startsWith("/ai/") ? aiRoute
+                            : url.pathname.startsWith("/sealed/") ? sealedRoute
+                                : url.pathname === "/members" || url.pathname.startsWith("/members/") || url.pathname === "/groups" ? members
+                                    : url.pathname === "/files" || url.pathname.startsWith("/files/") ? filesRoute
+                                        : url.pathname === "/badges" || url.pathname.startsWith("/badges/") || url.pathname.startsWith("/notifications") ? notificationsRoute : null;
         if (!route)
             return send(response, 404, { error: "not_found" });
         route(request, response, url).catch(() => { if (!response.headersSent)
@@ -572,6 +850,13 @@ export async function fakeChest(options = {}) {
         else
             response.destroy(); });
     });
+    // A page's connection: the Chest's side of the browser client.
+    server.on("upgrade", (request, socket) => {
+        const url = new URL(request.url ?? "/", "http://127.0.0.1");
+        if (url.pathname !== "/_chest/realtime" || !capabilities.has("realtime"))
+            return void socket.end("HTTP/1.1 404 Not Found\r\nContent-Length: 0\r\n\r\n");
+        realtime.upgrade(request, socket, url);
+    });
     await new Promise(resolve => server.listen(0, "127.0.0.1", resolve));
     const saved = Object.fromEntries(["CHEST_API", "CHEST_TOKEN", "CHEST_TOOL", "CHEST_ORGANIZATION", "CHEST_TIME_ZONE", "CHEST_LANGUAGE", "CHEST_CURRENCY", "CHEST_TEAM_URL", "CHEST_PUBLIC_URL"].map(name => [name, process.env[name]]));
     chest.api = "http://127.0.0.1:" + server.address().port;
@@ -593,13 +878,15 @@ export async function fakeChest(options = {}) {
         await answer.body?.cancel();
         return answer.status;
     };
-    const newId = (prefix) => prefix + Array.from(randomBytes(26), b => "abcdefghijklmnopqrstuvwxyz234567"[b & 31]).join("");
-    chest.emit = async (event, to) => {
-        const id = event.id ?? newId("evt_");
-        const body = JSON.stringify({ id, type: event.type, occurredAt: event.occurredAt ?? new Date().toISOString(), data: event.data });
+    chest.deliver = async (event, to) => {
+        const id = event.id ?? newId("evt_"), occurredAt = event.occurredAt ?? new Date().toISOString();
+        if ("source" in event) {
+            const body = JSON.stringify({ id, type: event.type, source: event.source, occurredAt, ...(event.subject === undefined ? {} : { subject: event.subject }), audience: event.audience ?? "all", data: event.data });
+            return post("/chest-events", eventChannel, id, body, to);
+        }
         if (event.type === "member.erased")
             erasures.add(event.data.erasure);
-        return post("/chest-events", eventChannel, id, body, to);
+        return post("/chest-events", eventChannel, id, JSON.stringify({ id, type: event.type, occurredAt, data: event.data }), to);
     };
     chest.run = async (name, to, run = {}) => {
         const id = run.id ?? newId("run_");
@@ -607,6 +894,8 @@ export async function fakeChest(options = {}) {
         return post("/chest-schedules", scheduleChannel, id, body, to);
     };
     chest.close = async () => {
+        realtime.close();
+        ticketOf = null;
         server.closeAllConnections();
         await new Promise(resolve => server.close(() => resolve()));
         for (const [name, value] of Object.entries(saved)) {