@argentic/chest-sdk 0.2.0 → 0.4.0

package/client/src/events.ts

@@ -1,9 +1,9 @@
-import { createHash, createHmac, timingSafeEqual } from "node:crypto";
 import type { IncomingMessage } from "node:http";
 import { ask, refusal } from "./api.js";
 import { ChestError, Unavailable } from "./errors.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":
@@ -26,8 +26,10 @@ import { forget } from "./members.js";
 // is out of sync and reconciles by listing its members (members.list) at its
 // next start. Every event also empties what members.lookup keeps.
 
-// What changed of a member the tool sees; "email" only with members.email.
-export type MemberChange = "name" | "photo" | "role" | "groups" | "email";
+// 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
+// zone they work in — what the tool writes to them, and at what hour.
+export type MemberChange = "name" | "photo" | "role" | "groups" | "email" | "language" | "timeZone";
 // Something the tool sees of a member who has it changed.
 export type MemberUpdated = { id: string; type: "member.updated"; occurredAt: string; data: { id: string; changed: MemberChange[] } };
 // The member lost access to the tool but stays in the Chest.
@@ -44,115 +46,21 @@ 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> };
 
-// Where handle() remembers the ids of the events already handled: a store
-// the tool chooses. Keep it durable — a table of the tool's database — so a
-// delivery made again after a restart of the tool is recognised:
-//
-//   create table chest_events (id text primary key, at timestamptz not null default now());
-//   const seen = {
-//     has: async (id: string) => (await sql`select 1 from chest_events where id = ${id}`).length > 0,
-//     add: async (id: string) => { await sql`insert into chest_events (id) values (${id}) on conflict do nothing`; },
-//   };
-export type Seen = { has(id: string): boolean | Promise<boolean>; add(id: string): void | Promise<void> };
-
-// memorySeen keeps the last limit ids in this process: lost at a restart,
-// enough for a tool whose handlers are idempotent anyway.
-export function memorySeen(limit = 10000): Seen {
-  const ids = new Set<string>();
-  return {
-    has: id => ids.has(id),
-    add: id => {
-      ids.delete(id);
-      ids.add(id);
-      while (ids.size > limit) ids.delete(ids.values().next().value as string);
-    },
-  };
-}
+// Where handle() remembers the ids of the events already handled (Seen), and
+// memorySeen, which keeps them in this process: shared with schedules.
+export { memorySeen, type Seen } from "./signed.js";
 
-// The key of the events is HMAC-SHA256 of this label under the text of
-// CHEST_TOKEN, exactly as the Chest derives it (chest/toolfront): neither the
-// token itself nor the key of the Chest-Member assertion.
-const label = "Chest-Event v1";
-const claims = ["aud", "iat", "exp", "jti", "digest"] as const;
-// Clocks of the Chest and of the container may differ by this much, in seconds.
-const skew = 5;
-const maxSignature = 2048;
-const maxBody = 64 << 10;
-const compact = /^([A-Za-z0-9_-]+)\.([A-Za-z0-9_-]+)\.([A-Za-z0-9_-]+)$/u;
-const eventIdPattern = /^evt_[a-z2-7]{26}$/u;
 // The grammar of an erasure's identifier, as the Chest mints it.
 export const erasureIdPattern = /^era_[a-z2-7]{26}$/u;
-const changes: readonly string[] = ["name", "photo", "role", "groups", "email"];
-
-function object(value: unknown): Record<string, unknown> | null {
-  return value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : null;
-}
-function json(raw: string): unknown {
-  try {
-    return JSON.parse(raw) as unknown;
-  } catch {
-    return null;
-  }
-}
-const instant = (v: unknown): v is string => typeof v === "string" && v.length <= 40 && !Number.isNaN(Date.parse(v));
-
-function headerOf(request: IncomingMessage | Request): string | null {
-  const headers = request.headers as Headers | IncomingMessage["headers"];
-  const value = typeof (headers as Headers).get === "function" ? (headers as Headers).get("chest-event") : (headers as IncomingMessage["headers"])["chest-event"];
-  return typeof value === "string" && value.length <= maxSignature ? value : null;
-}
-
-// bodyOf reads the body, 64 KiB at most; null beyond, or when it was read
-// already.
-async function bodyOf(request: IncomingMessage | Request): Promise<Buffer | null> {
-  try {
-    if (request instanceof Request) {
-      if (request.bodyUsed || Number(request.headers.get("content-length") ?? "0") > maxBody) return null;
-      const raw = Buffer.from(await request.arrayBuffer());
-      return raw.length <= maxBody ? raw : null;
-    }
-    const chunks: Buffer[] = [];
-    let size = 0;
-    for await (const chunk of request) {
-      size += (chunk as Buffer).length;
-      if (size > maxBody) return null;
-      chunks.push(chunk as Buffer);
-    }
-    return Buffer.concat(chunks);
-  } catch {
-    return null;
-  }
-}
+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 token = process.env["CHEST_TOKEN"];
-  const tool = process.env["CHEST_TOOL"];
-  if (!token || !/^[A-Za-z0-9_-]{43,512}$/u.test(token) || !tool || request.method !== "POST") return null;
-  const signature = headerOf(request);
-  const parts = signature === null ? null : compact.exec(signature);
-  if (!parts) return null;
-  const [, encodedHeader = "", encodedPayload = "", encodedSignature = ""] = parts;
-  const header = object(json(Buffer.from(encodedHeader, "base64url").toString("utf8")));
-  if (!header || Object.keys(header).length !== 2 || header["alg"] !== "HS256" || header["typ"] !== "JWT") return null;
-  const key = createHmac("sha256", Buffer.from(token, "utf8")).update(label).digest();
-  const expected = createHmac("sha256", key).update(encodedHeader + "." + encodedPayload).digest();
-  const given = Buffer.from(encodedSignature, "base64url");
-  if (given.length !== expected.length || !timingSafeEqual(given, expected)) return null;
-  const payload = object(json(Buffer.from(encodedPayload, "base64url").toString("utf8")));
-  if (!payload || Object.keys(payload).length !== claims.length || !claims.every(name => Object.hasOwn(payload, name))) return null;
-  const { aud, iat, exp, jti, digest } = payload;
-  if (aud !== tool || typeof jti !== "string" || !eventIdPattern.test(jti) || typeof digest !== "string") return null;
-  if (typeof iat !== "number" || !Number.isSafeInteger(iat) || typeof exp !== "number" || !Number.isSafeInteger(exp) || exp <= iat) return null;
-  const now = Math.floor(Date.now() / 1000);
-  if (iat > now + skew || exp <= now - skew) return null;
-  const body = await bodyOf(request);
-  if (body === null) return null;
-  const sum = createHash("sha256").update(body).digest();
-  const told = Buffer.from(digest, "base64url");
-  if (told.length !== sum.length || !timingSafeEqual(told, sum)) return 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;
   const data = object(e["data"]);

package/client/src/files.ts

@@ -1,4 +1,4 @@
-import { json, read, ask as chest, refusal as refused } from "./api.js";
+import { chestLink, json, read, ask as chest, refusal as refused } from "./api.js";
 import { ChestError, TooLarge, Unavailable } from "./errors.js";
 
 // The private files of a server tool whose chest.json declares
@@ -18,8 +18,9 @@ import { ChestError, TooLarge, Unavailable } from "./errors.js";
 // not reached), ChestError otherwise (invalid_name, invalid_type,
 // no_thumbnail 400, not_found 404…).
 
-// width and height: of a JPEG, PNG, GIF or WebP image the Chest measured.
-export type FileObject = { name: string; type: string; size: number; updated: string; width?: number; height?: number };
+// sha256: the digest of the content, in hex, as the Chest took it; width and
+// height: of a JPEG, PNG, GIF or WebP image the Chest measured.
+export type FileObject = { name: string; type: string; size: number; sha256: string; updated: string; width?: number; height?: number };
 export type FileData = { data: Uint8Array; type: string; size: number };
 export type FilePage = { files: FileObject[]; next: string | null };
 
@@ -31,8 +32,7 @@ const namePattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}(\/[A-Za-z0-9][A-Za-z0-9._-
 // family (RFC 6838 names).
 const typePattern = /^[a-z0-9][a-z0-9!#$&^_.+-]{0,62}\/(\*|[a-z0-9][a-z0-9!#$&^_.+-]{0,62})$/u;
 // Where the team host serves a link, and where it takes an upload.
-const linkPattern = /^https:\/\/[A-Za-z0-9.-]{1,253}(:[0-9]{1,5})?\/_chest\/files\/([A-Za-z0-9_-]+\.[A-Za-z0-9_-]+)$/u;
-const uploadPattern = /^https:\/\/[A-Za-z0-9.-]{1,253}(:[0-9]{1,5})?\/_chest\/files\/upload\/([A-Za-z0-9_-]+\.[A-Za-z0-9_-]+)$/u;
+const linkPath = "/_chest/files/", uploadPath = "/_chest/files/upload/";
 // The longest an upload may wait, in seconds.
 const uploadLife = 900;
 
@@ -47,7 +47,7 @@ const refusal = (response: Response) => refused(response, "files");
 function isObject(value: unknown): value is FileObject {
   if (!value || typeof value !== "object" || Array.isArray(value)) return false;
   const o = value as Record<string, unknown>;
-  return typeof o["name"] === "string" && namePattern.test(o["name"]) && typeof o["type"] === "string" && o["type"].length <= 200 && typeof o["size"] === "number" && Number.isSafeInteger(o["size"]) && o["size"] >= 0 && typeof o["updated"] === "string" && isSide(o["width"]) && isSide(o["height"]) && (o["width"] === undefined) === (o["height"] === undefined);
+  return typeof o["name"] === "string" && namePattern.test(o["name"]) && typeof o["type"] === "string" && o["type"].length <= 200 && typeof o["size"] === "number" && Number.isSafeInteger(o["size"]) && o["size"] >= 0 && typeof o["sha256"] === "string" && /^[a-f0-9]{64}$/u.test(o["sha256"]) && typeof o["updated"] === "string" && isSide(o["width"]) && isSide(o["height"]) && (o["width"] === undefined) === (o["height"] === undefined);
 }
 // isSide accepts a side of an image the Chest measured, or none.
 function isSide(value: unknown): boolean {
@@ -55,7 +55,7 @@ function isSide(value: unknown): boolean {
 }
 function object(value: unknown): FileObject {
   if (!isObject(value)) throw new Unavailable();
-  return { name: value.name, type: value.type, size: value.size, updated: value.updated, ...(value.width !== undefined ? { width: value.width, height: value.height! } : {}) };
+  return { name: value.name, type: value.type, size: value.size, sha256: value.sha256, updated: value.updated, ...(value.width !== undefined ? { width: value.width, height: value.height! } : {}) };
 }
 
 // put keeps data as the file name, of type type (application/octet-stream
@@ -157,7 +157,7 @@ export async function url(name: string, options: { thumbnail?: 256 | 1024; downl
   const response = await ask("POST", "/files/url", { body: JSON.stringify(command), type: "application/json" });
   if (response.status !== 200) throw await refusal(response);
   const body = (await json(response)) as { url?: unknown; expires_in?: unknown } | null;
-  const token = body && typeof body.url === "string" ? linkPattern.exec(body.url)?.[2] : undefined;
+  const token = body ? chestLink(body.url, linkPath) : undefined;
   if (!body || token === undefined || token.length > 1536 || typeof body.expires_in !== "number" || !Number.isInteger(body.expires_in) || body.expires_in <= 0) throw new Unavailable();
   return { url: body.url as string, expiresIn: body.expires_in };
 }
@@ -181,7 +181,7 @@ export async function uploadUrl(name: string, options: { maxSize?: number; types
   const response = await ask("POST", "/files/upload-url", { body: JSON.stringify(command), type: "application/json" });
   if (response.status !== 200) throw await refusal(response);
   const body = (await json(response)) as { url?: unknown; method?: unknown; expires_in?: unknown } | null;
-  const token = body && typeof body.url === "string" ? uploadPattern.exec(body.url)?.[2] : undefined;
+  const token = body ? chestLink(body.url, uploadPath) : undefined;
   if (!body || token === undefined || token.length > 2048 || body.method !== "PUT" || typeof body.expires_in !== "number" || !Number.isInteger(body.expires_in) || body.expires_in < 1 || body.expires_in > uploadLife) throw new Unavailable();
   return { url: body.url as string, method: "PUT", expiresIn: body.expires_in };
 }

package/client/src/member.ts

@@ -14,6 +14,14 @@ import type { IncomingMessage } from "node:http";
 //   declares: null when there is none.
 // - isBuilder says they build this tool; groups are the groups that give them
 //   this tool ("grp_…").
+// - language is the language the Chest speaks to this member (their own,
+//   else the Chest's default): a BCP 47 primary tag the product speaks
+//   ("en", "fr"…). The tool's private part (/chest) speaks it to them; a
+//   notification or an email to them is written in it.
+// - timeZone is the IANA zone the member works in ("America/New_York"):
+//   the one they chose in their profile, else their browser's, else the
+//   Chest's. Show them times in it; remind them at their hour in it. The
+//   company's day and business rules are the Chest's (chest.timeZone).
 // - email is there only when the tool holds "members.email".
 export type Member = {
   id: string;
@@ -25,22 +33,34 @@ export type Member = {
   isAdmin: boolean;
   isBuilder: boolean;
   groups: string[];
+  language: string;
+  timeZone: string;
   email?: string;
 };
+// What is the same for every member — the organization, the company's time
+// zone — is the Chest's: the chest module.
 
 // The grammars of the identifiers the Chest mints: a tool may check with them
 // the identifiers it stores.
 export const memberIdPattern = /^mbr_[a-z2-7]{26}$/u;
 export const groupIdPattern = /^grp_[a-z2-7]{26}$/u;
+// The grammar of a language the Chest gives: a primary tag, whichever the
+// product speaks (a language added to the Chest needs no change here); of a
+// zone: UTC, or an area and a location ("Europe/Paris",
+// "America/Argentina/Buenos_Aires").
+export const languagePattern = /^[a-z]{2,3}$/u;
+export const timeZonePattern = /^(?:UTC|[A-Z][A-Za-z_]{1,31}(?:\/[A-Za-z0-9_+-]{1,31}){1,2})$/u;
 
 // The key of the assertions is HMAC-SHA256 of this label under the text of
 // CHEST_TOKEN, exactly as the Chest derives it (chest/toolfront). Its version
-// is the shape of the claims: an assertion of another shape is refused. This
-// module stands alone (node:* only), so that it can be copied by itself.
+// changes when a claim changes meaning or goes, so that an assertion of
+// another shape is refused rather than misread; a claim added keeps it, as a
+// reader of the former claims still reads them. This module stands alone
+// (node:* only), so that it can be copied by itself.
 const label = "Chest-Member v2";
 // The claims every assertion carries; email only for a tool that holds
 // members.email.
-const claims = ["iss", "aud", "iat", "exp", "sub", "given_name", "family_name", "name", "picture", "role", "admin", "builder", "groups"] as const;
+const claims = ["iss", "aud", "iat", "exp", "sub", "given_name", "family_name", "name", "picture", "role", "admin", "builder", "groups", "language", "time_zone"] as const;
 // Clocks of the Chest and of the container may differ by this much, in seconds.
 const skew = 5;
 // An assertion is a few hundred bytes; anything longer is not one.
@@ -87,12 +107,13 @@ export function member(request: IncomingMessage | Request): Member | null {
   if (signature.length !== expected.length || !timingSafeEqual(signature, expected)) return null;
   const payload = json(encodedPayload);
   if (!payload || !claims.every(name => Object.hasOwn(payload, name))) return null;
-  const { iss, aud, iat, exp, sub, given_name, family_name, name, email, picture, role, admin, builder, groups } = payload;
+  const { iss, aud, iat, exp, sub, given_name, family_name, name, email, picture, role, admin, builder, groups, language, time_zone } = payload;
   if (typeof iss !== "string" || iss === "" || aud !== tool || typeof sub !== "string" || !memberIdPattern.test(sub)) return null;
   if (typeof iat !== "number" || !Number.isSafeInteger(iat) || typeof exp !== "number" || !Number.isSafeInteger(exp) || exp <= iat) return null;
   const now = Math.floor(Date.now() / 1000);
   if (iat > now + skew || exp <= now - skew) return null;
   if (typeof given_name !== "string" || typeof family_name !== "string" || typeof name !== "string" || typeof picture !== "string" || typeof role !== "string" || typeof admin !== "boolean" || typeof builder !== "boolean") return null;
   if (!Array.isArray(groups) || groups.length > 16 || !groups.every(g => typeof g === "string" && groupIdPattern.test(g)) || (email !== undefined && typeof email !== "string")) return null;
-  return { id: sub, firstName: given_name, lastName: family_name, name, photo: picture === "" ? null : picture, role: role === "" ? null : role, isAdmin: admin, isBuilder: builder, groups: [...groups] as string[], ...(email === undefined ? {} : { email }) };
+  if (typeof language !== "string" || !languagePattern.test(language) || typeof time_zone !== "string" || !timeZonePattern.test(time_zone)) return null;
+  return { id: sub, firstName: given_name, lastName: family_name, name, photo: picture === "" ? null : picture, role: role === "" ? null : role, isAdmin: admin, isBuilder: builder, groups: [...groups] as string[], language, timeZone: time_zone, ...(email === undefined ? {} : { email }) };
 }

package/client/src/members.ts

@@ -1,12 +1,13 @@
 import { ask, json, refusal } from "./api.js";
 import { ChestError, Unavailable } from "./errors.js";
-import { groupIdPattern, memberIdPattern, type Member } from "./member.js";
+import { groupIdPattern, languagePattern, memberIdPattern, timeZonePattern, type Member } from "./member.js";
 
 // Who has the tool, for a server tool whose chest.json declares
 // "capabilities": ["members"] (and "members.email" for their addresses):
 // exactly the members who have access to it at the time of the call — by a
-// grant, a group, open to all, or because they run it. A member without
-// access is indistinguishable from an identifier that does not exist.
+// grant, a group, open to all, or because they run it. list and get see
+// only them; lookup also names those the tool had who no longer have it
+// (FormerMember), so that what they did keeps its author.
 //
 //   import * as members from "@argentic/chest-sdk/members";
 //   const { members: page, next } = await members.list({ q: "cam" });
@@ -21,12 +22,15 @@ import { groupIdPattern, memberIdPattern, type Member } from "./member.js";
 
 // A page of the list, and the cursor of the next one (null after the last).
 export type MemberPage = { members: Member[]; next: string | null };
-// A member who left the Chest after having the tool: "former" with the name
-// they had, or "erased" without any once the owner had their data erased —
-// render “Former member”.
-export type FormerMember = { id: string; name: string | null; status: "former" | "erased" };
-// What a lookup found: members who have the tool, former members, and
-// identifiers the tool does not know.
+// Someone the tool had who no longer has it: "no_access" with their name, a
+// member of the Chest who lost access to the tool — render “Léa Dubois (no
+// access)” —; "former" with the name they had, a member who left the Chest —
+// “Léa Dubois (former member)” —; or "erased" without any once the owner had
+// their data erased — “Former member”.
+export type FormerMember = { id: string; name: string | null; status: "no_access" | "former" | "erased" };
+// What a lookup found: members who have the tool, those it had who no
+// longer have it, and identifiers the tool does not know — never had, or
+// forgotten.
 export type Lookup = { members: Member[]; former: FormerMember[]; unknown: string[] };
 // A group that gives the tool, with the identifiers of its members.
 export type Group = { id: string; name: string; members: string[] };
@@ -47,8 +51,8 @@ const text = (value: unknown, max: number): value is string => typeof value ===
 // Chest's answer.
 function shown(value: unknown): Member {
   const m = value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : null;
-  if (!m || typeof m["id"] !== "string" || !memberIdPattern.test(m["id"]) || !text(m["first_name"], 256) || !text(m["last_name"], 256) || !text(m["name"], 520) || !(m["photo"] === null || text(m["photo"], 200)) || !(m["role"] === null || text(m["role"], 48)) || typeof m["admin"] !== "boolean" || typeof m["builder"] !== "boolean" || !Array.isArray(m["groups"]) || m["groups"].length > 16 || !m["groups"].every(g => typeof g === "string" && groupIdPattern.test(g)) || !(m["email"] === undefined || text(m["email"], 254))) throw new Unavailable();
-  return { id: m["id"], firstName: m["first_name"], lastName: m["last_name"], name: m["name"], photo: m["photo"], role: m["role"], isAdmin: m["admin"], isBuilder: m["builder"], groups: [...m["groups"]] as string[], ...(m["email"] === undefined ? {} : { email: m["email"] }) };
+  if (!m || typeof m["id"] !== "string" || !memberIdPattern.test(m["id"]) || !text(m["first_name"], 256) || !text(m["last_name"], 256) || !text(m["name"], 520) || !(m["photo"] === null || text(m["photo"], 200)) || !(m["role"] === null || text(m["role"], 48)) || typeof m["admin"] !== "boolean" || typeof m["builder"] !== "boolean" || !Array.isArray(m["groups"]) || m["groups"].length > 16 || !m["groups"].every(g => typeof g === "string" && groupIdPattern.test(g)) || typeof m["language"] !== "string" || !languagePattern.test(m["language"]) || typeof m["time_zone"] !== "string" || !timeZonePattern.test(m["time_zone"]) || !(m["email"] === undefined || text(m["email"], 254))) throw new Unavailable();
+  return { id: m["id"], firstName: m["first_name"], lastName: m["last_name"], name: m["name"], photo: m["photo"], role: m["role"], isAdmin: m["admin"], isBuilder: m["builder"], groups: [...m["groups"]] as string[], language: m["language"], timeZone: m["time_zone"], ...(m["email"] === undefined ? {} : { email: m["email"] }) };
 }
 
 // list says the members who have the tool, by name then identifier, limit
@@ -76,8 +80,9 @@ export async function list(options: { after?: string; limit?: number; q?: string
   return { members: page.members.map(shown), next: page.next };
 }
 
-// get is the member of that identifier, or null when the tool does not know
-// them: never a member, a former one, or one without access.
+// get is the member of that identifier, or null when they do not have the
+// tool: never a member, a former one, or one without access (lookup names
+// the last two).
 export async function get(id: string): Promise<Member | null> {
   const response = await ask("members", "GET", "/members/" + checkId(id));
   if (response.status === 404) {
@@ -106,8 +111,8 @@ function keep(id: string, answer: Omit<Known, "at">): void {
 }
 
 // lookup resolves identifiers, each once, in the order given: the members
-// who have the tool, the former members who had it, and the identifiers it
-// does not know. Any number of them: the SDK asks 200 at a time, and keeps
+// who have the tool, those it had who no longer have it, and the identifiers
+// it does not know. Any number of them: the SDK asks 200 at a time, and keeps
 // each answer a minute.
 export async function lookup(ids: Iterable<string>): Promise<Lookup> {
   const wanted = [...new Set([...ids].map(checkId))];
@@ -129,7 +134,7 @@ export async function lookup(ids: Iterable<string>): Promise<Lookup> {
     }
     for (const value of answer.former) {
       const f = value as { id?: unknown; name?: unknown; status?: unknown } | null;
-      if (!f || typeof f.id !== "string" || !memberIdPattern.test(f.id) || !(f.status === "former" ? f.name === undefined || text(f.name, 520) : f.status === "erased" && f.name === undefined)) throw new Unavailable();
+      if (!f || typeof f.id !== "string" || !memberIdPattern.test(f.id) || !(f.status === "former" ? f.name === undefined || text(f.name, 520) : f.status === "no_access" ? text(f.name, 520) : f.status === "erased" && f.name === undefined)) throw new Unavailable();
       keep(f.id, { former: { id: f.id, name: (f.name as string | undefined) ?? null, status: f.status as FormerMember["status"] } });
       told.add(f.id);
     }

package/client/src/schedules.ts

@@ -0,0 +1,87 @@
+import type { IncomingMessage } from "node:http";
+import { delivery, instant, json, memorySeen, object, scheduleChannel, type Seen } from "./signed.js";
+
+// Work a server tool does by itself, at set times, without anyone opening
+// it: a morning digest, reminders, a purge, a badge kept true overnight.
+// Nothing runs in the tool's container between requests — the tool may be
+// asleep —: the Chest calls it. Its chest.json declares each schedule, a
+// name and a cron line read on the wall clock of the Chest's time zone
+// (chest.timeZone), which the owner approves in words ("Runs by itself:
+// morning, weekdays at 7:30 AM"):
+//
+//   "schedules": [{ "name": "morning", "cron": "30 7 * * 1-5" }]
+//
+// At each time, the Chest posts the run to the tool's POST /chest-schedules,
+// through its launcher only (never from the Internet), signed for this tool,
+// the tool woken first when it sleeps:
+//
+//   // app/chest-schedules/route.ts (Next.js): outside /chest, never behind a session
+//   import * as schedules from "@argentic/chest-sdk/schedules";
+//   export async function POST(request: Request) {
+//     return new Response(null, { status: await schedules.handle(request, {
+//       morning: async run => { await remindDueToday(); },
+//     }, { seen }) });
+//   }
+//
+// The tool answers once its work is done, within 5 minutes. A run is
+// delivered at least once, with the same id every time: one not answered
+// with a success is delivered again after 1, 5 and 15 minutes (run.attempt
+// counts, 4 at most), unless the next time of its schedule comes first.
+// Runs of one schedule never overlap: a time that comes while the previous
+// run still runs is skipped. A server that was stopped runs a missed time
+// once when it starts again. Whoever runs the tool sees each run on its
+// page, and may run a schedule now.
+//
+// Bounds (the Chest's): 8 schedules, each 15 minutes apart at least; 5
+// minutes a run.
+
+// A run: its id ("run_…", the same on every delivery of it), its schedule,
+// the time it stands for (RFC 3339, UTC: a run asked now stands for the time
+// it was asked), and its attempt (1 to 4).
+export type Run = { id: string; name: string; scheduledAt: string; attempt: number };
+
+// What handle() calls for each schedule, by its name.
+export type Handlers = Record<string, (run: Run) => void | Promise<void>>;
+
+export type { Seen };
+
+// The grammar of a schedule's name, as the Chest keeps it.
+const scheduleNamePattern = /^[a-z][a-z0-9-]{0,31}$/u;
+
+// verify returns the run a delivery carries, or null when it is not one the
+// Chest made for this tool: not a POST, no or another signature, another
+// tool, expired, a body other than the one signed or not of a run's shape.
+// It reads the body (1 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<Run | null> {
+  const signed = await delivery(request, scheduleChannel);
+  if (!signed) return null;
+  const r = object(json(signed.body.toString("utf8")));
+  if (!r || Object.keys(r).sort().join(",") !== "attempt,id,name,scheduledAt" || r["id"] !== signed.id) return null;
+  const { name, scheduledAt, attempt } = r;
+  if (typeof name !== "string" || !scheduleNamePattern.test(name) || !instant(scheduledAt) || typeof attempt !== "number" || !Number.isInteger(attempt) || attempt < 1 || attempt > 4) return null;
+  return { id: signed.id, name, scheduledAt, attempt };
+}
+
+const remembered = memorySeen();
+
+// handle verifies one delivery and runs the handler of its schedule, once:
+// the status to answer the Chest. 401 for a delivery that is not the
+// Chest's; 404 for a schedule without a handler (the Chest does not try
+// again: the version in service does not do it); 204 once the handler
+// returned, or for a run already handled (seen.has). A handler that throws
+// leaves the run unseen and handle throws: answer 500, the Chest delivers
+// it again. seen is the store of the runs handled (memorySeen by default,
+// lost at a restart: give a durable one — events' store serves both, the
+// ids never meet).
+export async function handle(request: IncomingMessage | Request, handlers: Handlers, options: { seen?: Seen } = {}): Promise<number> {
+  const run = await verify(request);
+  if (!run) return 401;
+  const handler = Object.hasOwn(handlers, run.name) ? handlers[run.name] : undefined;
+  if (!handler) return 404;
+  const seen = options.seen ?? remembered;
+  if (await seen.has(run.id)) return 204;
+  await handler(run);
+  await seen.add(run.id);
+  return 204;
+}

package/client/src/signed.ts

@@ -0,0 +1,166 @@
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+import type { IncomingMessage } from "node:http";
+
+// What the Chest signs for a server tool — the events of its members
+// (events), the runs of its schedules (schedules), posted through its
+// launcher only (never from the Internet), each on a route of its own —: one
+// mechanism, shared by the modules that read it and by testing, which signs
+// as the Chest. Not a published module. member.ts reads the Chest-Member
+// assertion with the same steps in its own words: it imports nothing but
+// node:*, so that a tool may vendor it alone (Forms does, and webpack does
+// not resolve a relative ./x.js import to ./x.ts).
+//
+// The signature is a compact JWS, HS256, typ JWT, in the channel's header,
+// under HMAC-SHA256 of the channel's label keyed by the text of CHEST_TOKEN,
+// exactly as the Chest derives it (chest/toolfront) — neither the token
+// itself nor the key of the Chest-Member assertion, and never another
+// channel's: a delivery of one is never read as the other's. Its claims are
+// the tool (aud), iat, exp, the identifier of what is posted (jti) and the
+// SHA-256 of the body (digest, base64url).
+
+// A channel: the header of its signature, the label its key derives from,
+// the grammar of its identifiers and the largest body it carries.
+export type Channel = { header: string; label: string; id: RegExp; maxBody: number };
+
+// The events of the members (events): POST /chest-events.
+export const eventChannel: Channel = { header: "Chest-Event", label: "Chest-Event v1", id: /^evt_[a-z2-7]{26}$/u, maxBody: 64 << 10 };
+// The runs of the schedules (schedules): POST /chest-schedules.
+export const scheduleChannel: Channel = { header: "Chest-Schedule", label: "Chest-Schedule v1", id: /^run_[a-z2-7]{26}$/u, maxBody: 1024 };
+
+const claims = ["aud", "iat", "exp", "jti", "digest"] as const;
+// Clocks of the Chest and of the container may differ by this much, in seconds.
+const skew = 5;
+const maxSignature = 2048;
+const compact = /^([A-Za-z0-9_-]+)\.([A-Za-z0-9_-]+)\.([A-Za-z0-9_-]+)$/u;
+
+export function object(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : null;
+}
+export function json(raw: string): unknown {
+  try {
+    return JSON.parse(raw) as unknown;
+  } catch {
+    return null;
+  }
+}
+// An instant as the Chest writes it (RFC 3339).
+export const instant = (v: unknown): v is string => typeof v === "string" && v.length <= 40 && !Number.isNaN(Date.parse(v));
+
+// headerValue is the value of a header, maxLength at most; null for none,
+// longer, or repeated (a Web Request joins repeated values with ", ", which
+// no signature contains; a Node request keeps them as an array).
+export function headerValue(request: IncomingMessage | Request, name: string, maxLength: number): string | null {
+  const headers = request.headers as Headers | IncomingMessage["headers"];
+  const value = typeof (headers as Headers).get === "function" ? (headers as Headers).get(name) : (headers as IncomingMessage["headers"])[name];
+  return typeof value === "string" && value.length <= maxLength ? value : null;
+}
+
+// signedClaims reads what the Chest signed for this tool under a label: the
+// claims of a compact JWS, HS256, typ JWT, under HMAC-SHA256 of the label
+// keyed by the text of CHEST_TOKEN, when the signature holds, its audience
+// is CHEST_TOOL and now is within iat and exp (5 s of skew each way); null
+// otherwise, or outside a Chest. It never throws for what it is given.
+export function signedClaims(value: string | null, label: string): Record<string, unknown> | null {
+  const token = process.env["CHEST_TOKEN"];
+  const tool = process.env["CHEST_TOOL"];
+  if (!token || !/^[A-Za-z0-9_-]{43,512}$/u.test(token) || !tool) return null;
+  const parts = value === null ? null : compact.exec(value);
+  if (!parts) return null;
+  const [, encodedHeader = "", encodedPayload = "", encodedSignature = ""] = parts;
+  const header = object(json(Buffer.from(encodedHeader, "base64url").toString("utf8")));
+  if (!header || Object.keys(header).length !== 2 || header["alg"] !== "HS256" || header["typ"] !== "JWT") return null;
+  const key = createHmac("sha256", Buffer.from(token, "utf8")).update(label).digest();
+  const expected = createHmac("sha256", key).update(encodedHeader + "." + encodedPayload).digest();
+  const given = Buffer.from(encodedSignature, "base64url");
+  if (given.length !== expected.length || !timingSafeEqual(given, expected)) return null;
+  const payload = object(json(Buffer.from(encodedPayload, "base64url").toString("utf8")));
+  if (!payload || payload["aud"] !== tool) return null;
+  const { iat, exp } = payload;
+  if (typeof iat !== "number" || !Number.isSafeInteger(iat) || typeof exp !== "number" || !Number.isSafeInteger(exp) || exp <= iat) return null;
+  const now = Math.floor(Date.now() / 1000);
+  return iat > now + skew || exp <= now - skew ? null : payload;
+}
+
+// signClaims is what the Chest would sign under a label for these claims
+// (their aud, iat and exp included), with that token: for the fake Chest of
+// a tool's tests (testing).
+export function signClaims(label: string, claims: Record<string, unknown>, token: string): string {
+  const encode = (value: unknown): string => Buffer.from(JSON.stringify(value)).toString("base64url");
+  const signed = encode({ alg: "HS256", typ: "JWT" }) + "." + encode(claims);
+  const key = createHmac("sha256", Buffer.from(token, "utf8")).update(label).digest();
+  return signed + "." + createHmac("sha256", key).update(signed).digest("base64url");
+}
+
+// bodyOf reads the body, limit bytes at most; null beyond, or when it was
+// read already.
+async function bodyOf(request: IncomingMessage | Request, limit: number): Promise<Buffer | null> {
+  try {
+    if (request instanceof Request) {
+      if (request.bodyUsed || Number(request.headers.get("content-length") ?? "0") > limit) return null;
+      const raw = Buffer.from(await request.arrayBuffer());
+      return raw.length <= limit ? raw : null;
+    }
+    const chunks: Buffer[] = [];
+    let size = 0;
+    for await (const chunk of request) {
+      size += (chunk as Buffer).length;
+      if (size > limit) return null;
+      chunks.push(chunk as Buffer);
+    }
+    return Buffer.concat(chunks);
+  } catch {
+    return null;
+  }
+}
+
+// delivery reads a request of a channel: the identifier it was signed for
+// and its body, when the signature, the tool, the time and the digest of
+// the body hold; null otherwise — not a POST, no or another signature,
+// another tool, expired, a body other than the one signed. It reads the
+// body. It never throws for what a request carries.
+export async function delivery(request: IncomingMessage | Request, channel: Channel): Promise<{ id: string; body: Buffer } | null> {
+  if (request.method !== "POST") return null;
+  const payload = signedClaims(headerValue(request, channel.header.toLowerCase(), maxSignature), channel.label);
+  if (!payload || Object.keys(payload).length !== claims.length || !claims.every(name => Object.hasOwn(payload, name))) return null;
+  const { jti, digest } = payload;
+  if (typeof jti !== "string" || !channel.id.test(jti) || typeof digest !== "string") return null;
+  const body = await bodyOf(request, channel.maxBody);
+  if (body === null) return null;
+  const sum = createHash("sha256").update(body).digest();
+  const told = Buffer.from(digest, "base64url");
+  if (told.length !== sum.length || !timingSafeEqual(told, sum)) return null;
+  return { id: jti, body };
+}
+
+// sign is the value of a channel's header the Chest would send with that
+// body: for the fake Chest of a tool's tests (testing).
+export function sign(channel: Channel, id: string, body: string, options: { token: string; tool: string }): string {
+  const iat = Math.floor(Date.now() / 1000);
+  return signClaims(channel.label, { aud: options.tool, iat, exp: iat + 60, jti: id, digest: createHash("sha256").update(body).digest("base64url") }, options.token);
+}
+
+// Where a handler remembers the identifiers of the deliveries already
+// handled: a store the tool chooses. Keep it durable — a table of the
+// tool's database — so a delivery made again after a restart of the tool is
+// recognised:
+//
+//   create table chest_seen (id text primary key, at timestamptz not null default now());
+//   const seen = {
+//     has: async (id: string) => (await sql`select 1 from chest_seen where id = ${id}`).length > 0,
+//     add: async (id: string) => { await sql`insert into chest_seen (id) values (${id}) on conflict do nothing`; },
+//   };
+export type Seen = { has(id: string): boolean | Promise<boolean>; add(id: string): void | Promise<void> };
+
+// memorySeen keeps the last limit ids in this process: lost at a restart,
+// enough for a tool whose handlers are idempotent anyway.
+export function memorySeen(limit = 10000): Seen {
+  const ids = new Set<string>();
+  return {
+    has: id => ids.has(id),
+    add: id => {
+      ids.delete(id);
+      ids.add(id);
+      while (ids.size > limit) ids.delete(ids.values().next().value as string);
+    },
+  };
+}