@argentic/chest-sdk 0.1.1 → 0.2.0

package/client/src/events.ts

@@ -0,0 +1,228 @@
+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";
+
+// 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:
+//
+//   // app/chest-events/route.ts (Next.js): outside /chest, never behind a session
+//   import * as events from "@argentic/chest-sdk/events";
+//   export async function POST(request: Request) {
+//     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),
+//     }, { 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.
+
+// What changed of a member the tool sees; "email" only with members.email.
+export type MemberChange = "name" | "photo" | "role" | "groups" | "email";
+// 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.
+export type AccessRevoked = { id: string; type: "access.revoked"; occurredAt: string; data: { id: string } };
+// The member left the Chest: members.lookup reads them "former".
+export type MemberRemoved = { id: string; type: "member.removed"; occurredAt: string; data: { id: string } };
+// 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.
+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> };
+
+// 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);
+    },
+  };
+}
+
+// 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;
+  }
+}
+
+// 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 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"]);
+  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 };
+  switch (e["type"]) {
+    case "member.updated": {
+      const changed = data["changed"];
+      if (keys !== "changed,id" || !Array.isArray(changed) || changed.length < 1 || changed.length > changes.length || !changed.every(c => typeof c === "string" && changes.includes(c)) || new Set(changed).size !== changed.length) return null;
+      return { known: true, event: { ...base, type: "member.updated", data: { id: data["id"], changed: [...changed] as MemberChange[] } } };
+    }
+    case "access.revoked":
+    case "member.removed":
+      return keys === "id" ? { known: true, event: { ...base, type: e["type"], data: { id: data["id"] } } } : null;
+    case "member.erased":
+      if (keys !== "deadline,erasure,id" || typeof data["erasure"] !== "string" || !erasureIdPattern.test(data["erasure"]) || !instant(data["deadline"])) return null;
+      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 } };
+}
+
+// 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> {
+  const read = await envelope(request);
+  return read?.known ? read.event : null;
+}
+
+const remembered = memorySeen();
+
+// 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> {
+  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);
+  await seen.add(event.id);
+  return 204;
+}
+
+// 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
+// (404, an erasure this tool was not told of), invalid_id (400),
+// CapabilityNotGranted (403: the version does not receive member events),
+// Unavailable.
+export async function acknowledgeErasure(erasure: string): Promise<void> {
+  if (typeof erasure !== "string" || !erasureIdPattern.test(erasure)) throw new ChestError("invalid_id", 400, "invalid erasure identifier");
+  const response = await ask("events", "POST", `/erasures/${erasure}/done`);
+  if (response.status === 204) return;
+  if (response.status < 400) {
+    await response.body?.cancel();
+    throw new Unavailable();
+  }
+  throw await refusal(response, "events");
+}

package/client/src/files.ts

@@ -1,115 +1,61 @@
-import { CapabilityNotGranted, ChestError, QuotaExceeded, TooLarge, Unavailable } from "./errors.js";
+import { 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
 // "capabilities": ["files"]: kept by its Chest (1 GiB, 10,000 objects, 32 MiB
-// each), never on the tool's own disk. The container has no network: the
-// Chest's API is at CHEST_API (http://127.0.0.1:<port>, the tool's launcher,
-// which relays each request to the Chest). A call reaches the tool's files
-// only: its instance is its identity.
+// each, unless the manifest asks otherwise: "files": {"quota", "maxObject"}),
+// never on the tool's own disk, through the Chest's API (CHEST_API, api.ts).
+// A call reaches the tool's files only: its instance is its identity.
 //
 //   import * as files from "@argentic/chest-sdk/files";
 //   await files.put("photos/cat.png", bytes, "image/png");
 //   const { url } = await files.url("photos/cat.png");   // 15 min, team host
+//   const up = await files.uploadUrl("photos/", { types: ["image/*"] }); // a member's browser sends it
 //
 // Names: up to 8 segments of 1–100 letters, digits, '.', '_' or '-',
 // separated by '/', none starting with '.' or '-'. Errors: CapabilityNotGranted
 // (403), TooLarge (413), QuotaExceeded (429), Unavailable (503, or the Chest
-// not reached), ChestError otherwise (invalid_name, invalid_type 400…).
+// not reached), ChestError otherwise (invalid_name, invalid_type,
+// no_thumbnail 400, not_found 404…).
 
-export type FileObject = { name: string; type: string; size: number; updated: string };
+// 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 };
 export type FileData = { data: Uint8Array; type: string; size: number };
 export type FilePage = { files: FileObject[]; next: string | null };
 
-const maxObject = 32 << 20;
-const maxAnswer = 4 << 20;
-const deadline = 120000;
+// The largest object a manifest may ask; the Chest holds each tool to its own.
+const maxObject = 512 << 20;
 // The grammar of a name, the same as the Chest's (chest/toolfiles, name).
 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;
-
-// base is the Chest's API as the launcher gives it; without, the version
-// does not keep files.
-function base(): string {
-  const value = process.env["CHEST_API"];
-  if (typeof value !== "string" || !/^http:\/\/127\.0\.0\.1:[1-9][0-9]{0,4}$/u.test(value) || Number(value.slice(17)) > 65535) throw new CapabilityNotGranted("files");
-  return value;
-}
+// A media type an upload accepts: without parameters, "family/*" for a whole
+// 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;
+// The longest an upload may wait, in seconds.
+const uploadLife = 900;
 
 function checkName(name: unknown): string {
   if (typeof name !== "string" || !namePattern.test(name)) throw new ChestError("invalid_name", 400, "invalid file name");
   return name;
 }
 
-// ask sends one request to the Chest; a failure to reach it is Unavailable.
-async function ask(method: string, path: string, init: { body?: Uint8Array<ArrayBuffer> | string; type?: string } = {}): Promise<Response> {
-  const headers: Record<string, string> = {};
-  if (init.type !== undefined) headers["Content-Type"] = init.type;
-  try {
-    return await fetch(base() + path, { method, headers, ...(init.body !== undefined ? { body: init.body } : {}), redirect: "error", signal: AbortSignal.timeout(deadline) });
-  } catch (error) {
-    if (error instanceof ChestError) throw error;
-    throw new Unavailable();
-  }
-}
-
-// read takes a body of limit bytes at most; beyond, or cut, the answer is not
-// the Chest's.
-async function read(response: Response, limit: number): Promise<Uint8Array> {
-  const declared = Number(response.headers.get("content-length") ?? "0");
-  if (declared > limit) throw new Unavailable();
-  const chunks: Uint8Array[] = [];
-  let size = 0;
-  try {
-    for await (const chunk of response.body ?? []) {
-      size += chunk.byteLength;
-      if (size > limit) throw new Unavailable();
-      chunks.push(chunk);
-    }
-  } catch {
-    throw new Unavailable();
-  }
-  const all = new Uint8Array(size);
-  let at = 0;
-  for (const chunk of chunks) {
-    all.set(chunk, at);
-    at += chunk.byteLength;
-  }
-  return all;
-}
-
-async function json(response: Response): Promise<unknown> {
-  try {
-    return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(await read(response, maxAnswer)));
-  } catch (error) {
-    if (error instanceof ChestError) throw error;
-    throw new Unavailable();
-  }
-}
-
-// refusal turns an answer that is not a success into what the tool tests.
-async function refusal(response: Response): Promise<ChestError> {
-  if (response.status === 403) return new CapabilityNotGranted("files");
-  if (response.status === 413) return new TooLarge();
-  if (response.status === 429) return new QuotaExceeded();
-  if (response.status >= 500) return new Unavailable();
-  let code = "refused";
-  try {
-    const body = await json(response);
-    const given = (body as { error?: unknown } | null)?.error;
-    if (typeof given === "string" && /^[a-z_]{1,40}$/u.test(given)) code = given;
-  } catch {
-    // The code stays "refused".
-  }
-  return new ChestError(code, response.status, `the Chest refused: ${code}`);
-}
+const ask = (method: string, path: string, init?: { body?: Uint8Array<ArrayBuffer> | string; type?: string }) => chest("files", method, path, init);
+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";
+  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);
+}
+// isSide accepts a side of an image the Chest measured, or none.
+function isSide(value: unknown): boolean {
+  return value === undefined || (typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 65536);
 }
 function object(value: unknown): FileObject {
   if (!isObject(value)) throw new Unavailable();
-  return { name: value.name, type: value.type, size: value.size, updated: value.updated };
+  return { name: value.name, type: value.type, size: value.size, 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
@@ -117,6 +63,7 @@ function object(value: unknown): FileObject {
 export async function put(name: string, data: Uint8Array | string, type?: string): Promise<FileObject> {
   checkName(name);
   if (!(data instanceof Uint8Array) && typeof data !== "string") throw new TypeError("data must be bytes or text");
+  if (data instanceof Uint8Array && data.byteLength > maxObject) throw new TooLarge();
   const body = typeof data === "string" ? new TextEncoder().encode(data) : new Uint8Array(data);
   if (body.byteLength > maxObject) throw new TooLarge();
   const response = await ask("PUT", "/files/" + name, { body, type: type ?? (typeof data === "string" ? "text/plain; charset=utf-8" : "application/octet-stream") });
@@ -168,15 +115,73 @@ async function remove(name: string): Promise<boolean> {
 }
 export { remove as delete };
 
+// stat says what the tool keeps as the file name, without reading it; null
+// when it has none of that name.
+export async function stat(name: string): Promise<FileObject | null> {
+  checkName(name);
+  const response = await ask("GET", "/files/" + name + "?stat");
+  if (response.status === 404) {
+    await response.body?.cancel();
+    return null;
+  }
+  if (response.status !== 200) throw await refusal(response);
+  const found = object(await json(response));
+  if (found.name !== name) throw new Unavailable();
+  return found;
+}
+
+// move renames the file from as to, at once, replacing the one named to;
+// ChestError not_found when the tool has none named from.
+export async function move(from: string, to: string): Promise<FileObject> {
+  checkName(from);
+  checkName(to);
+  const response = await ask("POST", "/files/move", { body: JSON.stringify({ from, to }), type: "application/json" });
+  if (response.status !== 200) throw await refusal(response);
+  const moved = object(await json(response));
+  if (moved.name !== to) throw new Unavailable();
+  return moved;
+}
+
 // url signs a link to the file as it is now, on the tool's team host: anyone
 // who has it opens the file, without signing in, for expiresIn seconds
-// (15 minutes), or until the file changes or goes. Give it to a member's
-// browser, never to a public page.
-export async function url(name: string): Promise<{ url: string; expiresIn: number }> {
+// (15 minutes), or until the file changes or goes. thumbnail links to the
+// image reduced to 256 or 1024 pixels (JPEG, PNG, GIF, WebP; ChestError
+// no_thumbnail otherwise); download has it saved rather than shown. Give it
+// to a member's browser, never to a public page.
+export async function url(name: string, options: { thumbnail?: 256 | 1024; download?: boolean } = {}): Promise<{ url: string; expiresIn: number }> {
   checkName(name);
-  const response = await ask("POST", "/files/url", { body: JSON.stringify({ name }), type: "application/json" });
+  const { thumbnail, download } = options;
+  if (thumbnail !== undefined && thumbnail !== 256 && thumbnail !== 1024) throw new ChestError("invalid_body", 400, "a thumbnail is 256 or 1024 pixels");
+  if (download !== undefined && typeof download !== "boolean") throw new TypeError("download must be true or false");
+  const command = { name, ...(thumbnail !== undefined ? { thumbnail } : {}), ...(download !== undefined ? { download } : {}) };
+  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;
-  if (!body || typeof body.url !== "string" || !/^https:\/\/[^/?#]+\/_chest\/files\/[A-Za-z0-9_.-]{1,1536}$/u.test(body.url) || typeof body.expires_in !== "number" || !Number.isInteger(body.expires_in) || body.expires_in <= 0) throw new Unavailable();
-  return { url: body.url, expiresIn: body.expires_in };
+  const token = body && typeof body.url === "string" ? linkPattern.exec(body.url)?.[2] : 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 };
+}
+
+// uploadUrl authorises one upload from a member's browser, which sends the
+// file itself to url, the tool's team host, with its session:
+//   fetch(up.url, { method: "PUT", body: file, headers: { "Content-Type": file.type } })
+// name is the object's, or a folder ending in '/' where the Chest names it;
+// maxSize bytes at most (the tool's largest object when not said), of types
+// (up to 8, "image/*" for a family; any when not said), within expiresIn
+// seconds (1–900, 900 when not said), once. Call it from a /chest route,
+// after member(); then stat the name before recording it.
+export async function uploadUrl(name: string, options: { maxSize?: number; types?: string[]; expiresIn?: number } = {}): Promise<{ url: string; method: "PUT"; expiresIn: number }> {
+  if (typeof name !== "string" || !(name.endsWith("/") ? namePattern.test(name.slice(0, -1)) && name.split("/").length <= 8 : namePattern.test(name))) throw new ChestError("invalid_name", 400, "invalid file or folder name");
+  const { maxSize, types, expiresIn } = options;
+  if (maxSize !== undefined && (typeof maxSize !== "number" || !Number.isSafeInteger(maxSize) || maxSize < 1)) throw new ChestError("invalid_body", 400, "maxSize is a number of bytes");
+  if (maxSize !== undefined && maxSize > maxObject) throw new TooLarge();
+  if (types !== undefined && (!Array.isArray(types) || types.length > 8 || types.some((t, i) => typeof t !== "string" || t.length > 100 || !typePattern.test(t) || types.indexOf(t) !== i))) throw new ChestError("invalid_type", 400, "invalid media types");
+  if (expiresIn !== undefined && (typeof expiresIn !== "number" || !Number.isInteger(expiresIn) || expiresIn < 1 || expiresIn > uploadLife)) throw new ChestError("invalid_body", 400, "expiresIn is 1 to 900 seconds");
+  const command = { name, ...(maxSize !== undefined ? { max_size: maxSize } : {}), ...(types !== undefined ? { types } : {}), ...(expiresIn !== undefined ? { expires_in: expiresIn } : {}) };
+  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;
+  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

@@ -1,30 +1,51 @@
 import { createHmac, timingSafeEqual } from "node:crypto";
 import type { IncomingMessage } from "node:http";
 
-// The member the Chest asserts on a request of the team host of a server
-// tool (/chest and below), read from the Chest-Member header. photo and role
-// are absent when the Chest names none.
+// A member of the Chest, as the tool sees them: on a request of its team host
+// (member), and in its members (members.ts).
+//
+// - id is the member's identifier in this Chest, "mbr_" and 26 characters:
+//   the same in every tool of the Chest, never reused, never derived from an
+//   address or an account. Store it; resolve names when rendering.
+// - name is "First Last", or the local part of the address when the member
+//   set no name.
+// - photo is the address of their picture on the tool's team host
+//   (/_chest/members/{id}/photo?v=<rev>), role one of the roles chest.json
+//   declares: null when there is none.
+// - isBuilder says they build this tool; groups are the groups that give them
+//   this tool ("grp_…").
+// - email is there only when the tool holds "members.email".
 export type Member = {
   id: string;
   firstName: string;
   lastName: string;
   name: string;
-  email: string;
-  photo?: string;
-  role?: string;
+  photo: string | null;
+  role: string | null;
   isAdmin: boolean;
   isBuilder: boolean;
+  groups: string[];
+  email?: string;
 };
 
+// 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 key of the assertions is HMAC-SHA256 of this label under the text of
-// CHEST_TOKEN, exactly as the Chest derives it (chest/toolfront).
-const label = "Chest-Member v1";
+// 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.
+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;
 // 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.
 const maxLength = 8192;
 const compact = /^([A-Za-z0-9_-]+)\.([A-Za-z0-9_-]+)\.([A-Za-z0-9_-]+)$/u;
-const claims = ["iss", "aud", "iat", "exp", "sub", "given_name", "family_name", "name", "email", "picture", "role", "admin", "builder"] as const;
 
 function assertionOf(request: IncomingMessage | Request): string | null {
   const headers = request.headers as Headers | IncomingMessage["headers"];
@@ -45,10 +66,11 @@ function json(part: string): Record<string, unknown> | null {
 
 // member returns who the Chest says is making this request, or null when the
 // request carries no valid assertion — absent, malformed, signed with another
-// key, for another tool, expired or not yet valid —, or when CHEST_TOKEN or
-// CHEST_TOOL is missing. It never throws for what a request carries. Only the
-// Chest's front reaches the tool; the signature is a second defence, and the
-// tool still decides what a member may do with its own rules.
+// key or for another shape, for another tool, expired or not yet valid —, or
+// when CHEST_TOKEN or CHEST_TOOL is missing. It never throws for what a
+// request carries. Only the Chest's front reaches the tool; the signature is a
+// second defence, and the tool still decides what a member may do with its
+// own rules.
 export function member(request: IncomingMessage | Request): Member | null {
   const token = process.env["CHEST_TOKEN"];
   const tool = process.env["CHEST_TOOL"];
@@ -65,11 +87,12 @@ 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 } = payload;
-  if (typeof iss !== "string" || iss === "" || aud !== tool || typeof sub !== "string" || sub === "") return null;
+  const { iss, aud, iat, exp, sub, given_name, family_name, name, email, picture, role, admin, builder, groups } = 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 email !== "string" || typeof picture !== "string" || typeof role !== "string" || typeof admin !== "boolean" || typeof builder !== "boolean") return null;
-  return { id: sub, firstName: given_name, lastName: family_name, name, email, ...(picture === "" ? {} : { photo: picture }), ...(role === "" ? {} : { role }), isAdmin: admin, isBuilder: builder };
+  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 }) };
 }