app/lab/members.server.ts

Functions

Imports

It imports app/db/members.ts, app/lab/access-sync.server.ts, app/lab/actor.server.ts, app/lab/forms.mjs, app/lab/titles.mjs. Imported by app/routes/workspace.members.tsx.

Source

1/**
2 * /lab/members: who may sign in to the lab, and every change to that list (capsid docs/design/design-identity-roles.md,
3 * "The members page"; docs/KNOWLEDGE-BASE.md step 5). The page is Capsomer's `people-roles`; this module is what it
4 * shows and what each of its posts does.
5 *
6 * Every rule is site-runtime's `checkChange`: nobody manages their own layer or anyone above it, and nobody grants a
7 * permission they do not hold. The page offering an action is never permission to take it, so every post is checked
8 * again here against the person's row as it is now. Each change is one batch (the row and its member_audit row), then
9 * one Access sync through Capsid (app/lab/access-sync.server.ts), whose answer lands on the audit row.
10 */
11
12import {
13  MANAGE_MEMBERS,
14  auditRow,
15  can,
16  checkChange,
17  defaultEndDate,
18  isExpired,
19  normalizeEmail,
20  reviewOpen,
21  type Actor,
22  type MemberRow,
23  type Title,
24} from "@dustinedwards/site-runtime/members";
25import type { HistoryEntry, PeopleData, PersonRow, TitleOption } from "capsomer/react/people-roles";
26
27import {
28  getMember,
29  latestSyncByEmail,
30  listMembers,
31  listTerms,
32  memberHistory,
33  writeMemberChange,
34  writeMemberChanges,
35  writeTerms,
36  type MemberAuditRow,
37  type SyncState,
38} from "~/db/members";
39
40import { SYNC_NOT_SET_UP, syncAccess } from "./access-sync.server";
41import { labRules } from "./actor.server";
42import { field, isDate } from "./forms.mjs";
43import { LAB_CATALOG, canEditTerms, titleLabel } from "./titles.mjs";
44
45type Fetch = (input: string, init?: RequestInit) => Promise<Response>;
46
47type MembersResult = { ok: boolean; text: string };
48
49export type MembersActionData = {
50  result?: MembersResult;
51  /** A removal posted with no script: the page asks first, and the confirm posts `confirmed=yes`. */
52  confirm?: { email: string; name: string };
53};
54
55export type MembersPageData = {
56  people: PeopleData;
57  terms: string[];
58  canEditTerms: boolean;
59  /** Shown above the list while this site holds no Capsid key, so nobody takes a saved change for an Access change. */
60  syncNotice: string | null;
61  primaryOwner: boolean;
62};
63
64const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
65
66function titleOf(id: string): Title | undefined {
67  return LAB_CATALOG.titles.get(id);
68}
69
70/** The person's row is below the actor's layer, so the actor may manage it, and it is not the actor's own. */
71function manages(actor: Actor, row: MemberRow): boolean {
72  const title = titleOf(row.title);
73  return can(actor, MANAGE_MEMBERS) && !!title && title.layer > actor.layer && row.email !== actor.email;
74}
75
76/** A title's default end date, or null when it does not expire or no term date is entered yet. */
77function safeDefault(title: Title, terms: string[], nowMs: number, after: string | null = null): string | null {
78  try {
79    return defaultEndDate(title, terms, nowMs, after);
80  } catch (error) {
81    if (error instanceof RangeError) return null;
82    throw error;
83  }
84}
85
86const NO_TERMS = "Enter this year's semester end dates first: a Lab worker's or Lab manager's access ends on one of them.";
87
88/** The titles the actor may give, below their layer and within what they hold; the least first, so it is the default. */
89function grantableTitles(actor: Actor): Title[] {
90  return [...LAB_CATALOG.titles.values()]
91    .filter((t) => t.layer > actor.layer && t.permissions.every((p) => actor.permissions.has(p)))
92    .sort((a, b) => b.layer - a.layer);
93}
94
95function syncOf(state: { cloudflare: SyncState; error: string | null } | undefined): Pick<PersonRow, "sync" | "syncError"> {
96  if (!state || state.cloudflare === "accepted" || state.cloudflare === "not_needed") return { sync: "ready" };
97  if (state.cloudflare === "pending") return { sync: "waiting" };
98  return { sync: "failed", syncError: state.error ?? undefined };
99}
100
101function personRow(
102  actor: Actor,
103  row: MemberRow,
104  terms: string[],
105  nowMs: number,
106  sync: Map<string, { cloudflare: SyncState; error: string | null }>,
107): PersonRow {
108  const title = titleOf(row.title);
109  const expired = row.status === "active" && isExpired(row, nowMs);
110  const status: PersonRow["status"] = expired ? "expired" : row.status;
111  const renewable = !!title?.expires && status !== "removed";
112  return {
113    email: row.email,
114    name: row.name || row.email,
115    title: titleLabel(row.title),
116    endDate: row.end_date,
117    status,
118    ...syncOf(sync.get(row.email)),
119    manageable: manages(actor, row),
120    renewTo: renewable && title ? safeDefault(title, terms, nowMs, row.end_date) : null,
121    you: row.email === actor.email,
122    ...(status === "expired" && row.end_date ? { endedOn: row.end_date } : {}),
123  };
124}
125
126function parsed(json: string | null): Partial<MemberRow> | null {
127  if (!json) return null;
128  try {
129    return JSON.parse(json) as Partial<MemberRow>;
130  } catch {
131    return null;
132  }
133}
134
135function historyEntry(row: Awaited<ReturnType<typeof memberHistory>>[number]): HistoryEntry {
136  const before = parsed(row.beforeRow);
137  const after = parsed(row.afterRow);
138  const cloudflare = row.cloudflare === "pending" || row.cloudflare === "failed" ? row.cloudflare : "accepted";
139  return {
140    at: row.at,
141    by: row.actor,
142    action: row.action as HistoryEntry["action"],
143    ...(before?.title ? { fromTitle: titleLabel(before.title) } : {}),
144    ...(after?.title ? { toTitle: titleLabel(after.title) } : {}),
145    ...(after ? { endDate: after.end_date ?? null } : {}),
146    ...(row.reason ? { reason: row.reason } : {}),
147    cloudflare,
148    ...(row.cloudflareError ? { cloudflareError: row.cloudflareError } : {}),
149  };
150}
151
152function plural(label: string): string {
153  return label.endsWith("s") ? label : `${label}s`;
154}
155
156function listText(words: string[]): string {
157  if (words.length <= 1) return words.join("");
158  return `${words.slice(0, -1).join(", ")} and ${words[words.length - 1]}`;
159}
160
161/** What the members page shows this actor: the people they may manage and themselves, never anyone else. */
162export async function membersPage(env: Env, actor: Actor, url: URL, nowMs: number): Promise<MembersPageData> {
163  const [rows, terms, sync] = await Promise.all([listMembers(env), listTerms(env), latestSyncByEmail(env)]);
164  const visible = rows.filter((row) => row.email === actor.email || manages(actor, row));
165  const people = visible.map((row) => personRow(actor, row, terms, nowMs, sync));
166  const titles: TitleOption[] = grantableTitles(actor).map((t) => ({ value: t.id, label: t.label, defaultEnd: safeDefault(t, terms, nowMs) }));
167
168  const reviewRows = visible.filter((row) => manages(actor, row) && reviewOpen(row, nowMs));
169  const review = reviewRows.length
170    ? {
171        endDate: reviewRows.map((r) => r.end_date as string).sort()[0] as string,
172        people: reviewRows.map((r) => {
173          const p = people.find((x) => x.email === r.email) as PersonRow;
174          return { email: p.email, name: p.name, title: p.title, renewTo: p.renewTo };
175        }),
176      }
177    : undefined;
178
179  const personParam = url.searchParams.get("person");
180  const shown = personParam ? visible.find((r) => r.email === personParam.toLowerCase()) : undefined;
181  const history = shown
182    ? { email: shown.email, name: shown.name || shown.email, entries: (await memberHistory(env, shown.email)).map(historyEntry) }
183    : undefined;
184
185  const changeParam = url.searchParams.get("change");
186  const changing = changeParam && visible.some((r) => r.email === changeParam.toLowerCase() && manages(actor, r)) ? changeParam.toLowerCase() : undefined;
187
188  const lead = titles.length
189    ? `You manage ${listText([...titles].reverse().map((t) => plural(t.label)))}.${terms.some((d) => d >= new Date(nowMs).toISOString().slice(0, 10)) ? "" : ` ${NO_TERMS}`}`
190    : undefined;
191
192  return {
193    people: {
194      heading: "Lab members",
195      ...(lead ? { lead } : {}),
196      people,
197      titles,
198      ...(review ? { review } : {}),
199      ...(history ? { history } : {}),
200      ...(changing ? { changing } : {}),
201    },
202    terms,
203    canEditTerms: canEditTerms(actor),
204    syncNotice: env.CAPSID_ACCESS_SYNC_KEY?.trim() ? null : SYNC_NOT_SET_UP,
205    primaryOwner: actor.layer === 0,
206  };
207}
208
209function refused(text: string): MembersActionData {
210  return { result: { ok: false, text } };
211}
212
213/** The sync's answer appended to a done change, so the result line never says more than Cloudflare has. */
214async function withSync(env: Env, nowMs: number, done: string, fetchImpl?: Fetch): Promise<MembersActionData> {
215  const outcome = await syncAccess(env, nowMs, fetchImpl);
216  if (outcome.ok) return { result: { ok: true, text: `${done} Cloudflare Access matches the list.` } };
217  return { result: { ok: true, text: `${done} Cloudflare Access does not match yet: ${outcome.error}` } };
218}
219
220function rulesFor(env: Env, terms: string[], nowMs: number) {
221  return { ...labRules(env, nowMs), termEnds: terms };
222}
223
224/** Runs one post from the members page as `actor`. Every branch re-checks with `checkChange`. */
225export async function membersAction(env: Env, actor: Actor, form: FormData, nowMs: number, fetchImpl?: Fetch): Promise<MembersActionData> {
226  const intent = field(form, "intent");
227  if (intent === "set_terms") return setTerms(env, actor, field(form, "terms"), nowMs);
228  if (!can(actor, MANAGE_MEMBERS)) return refused("You do not manage people here.");
229  if (intent === "retry") {
230    const outcome = await syncAccess(env, nowMs, fetchImpl);
231    return outcome.ok ? { result: { ok: true, text: "Cloudflare Access matches the list." } } : refused(outcome.error);
232  }
233  if (intent === "review") return review(env, actor, form, nowMs, fetchImpl);
234
235  const terms = await listTerms(env);
236  const rules = rulesFor(env, terms, nowMs);
237
238  if (intent === "add") {
239    const typed = field(form, "email");
240    if (!EMAIL.test(typed)) return refused("Type the email address they sign in with.");
241    const email = normalizeEmail(typed);
242    const titleId = field(form, "title");
243    const title = titleOf(titleId);
244    const endDate = title?.expires ? field(form, "end_date") || safeDefault(title, terms, nowMs) : null;
245    if (title?.expires && !endDate) return refused(NO_TERMS);
246    if (endDate && !isDate(endDate)) return refused(`Not a date (YYYY-MM-DD): ${endDate}.`);
247    const existing = await getMember(env, email);
248    if (existing && existing.status !== "removed") return refused(`${existing.name || email} is already on the list: renew them or change their title.`);
249    const verdict = check(actor, { kind: "add", email, title: titleId, end_date: endDate }, rules);
250    if (!verdict.ok) return refused(verdict.reason);
251    const after: MemberRow = { email, name: field(form, "name"), title: titleId, end_date: endDate, status: "active" };
252    await writeMemberChange(env, after, actor.email, audit(actor, "add", email, existing, after, nowMs));
253    return withSync(env, nowMs, `Added ${after.name || email} as ${titleLabel(titleId)}.`, fetchImpl);
254  }
255
256  const email = field(form, "email").toLowerCase();
257  const target = email ? await getMember(env, email) : null;
258  if (!target) return refused("That person is not on the list.");
259  const who = target.name || target.email;
260
261  if (intent === "change_title") {
262    const titleId = field(form, "title");
263    const reason = field(form, "reason");
264    if (target.status === "removed") return refused("A removed person is added again, not given a new title.");
265    const verdict = check(actor, { kind: "change_title", target, title: titleId, reason }, rules);
266    if (!verdict.ok) return refused(verdict.reason);
267    const title = titleOf(titleId) as Title;
268    // A date already passed is not kept: a new title for someone whose access ended starts at the next term end.
269    const current = target.end_date && !isExpired(target, nowMs) ? target.end_date : null;
270    const endDate = title.expires ? (current ?? safeDefault(title, terms, nowMs)) : null;
271    if (title.expires && !endDate) return refused(NO_TERMS);
272    const after: MemberRow = { ...target, title: titleId, end_date: endDate };
273    await writeMemberChange(env, after, actor.email, audit(actor, "change_title", email, target, after, nowMs, reason));
274    return withSync(env, nowMs, `${who} is now ${title.label}.`, fetchImpl);
275  }
276
277  if (intent === "renew") {
278    const verdict = check(actor, { kind: "renew", target }, rules);
279    if (!verdict.ok) return refused(verdict.reason);
280    const endDate = safeDefault(titleOf(target.title) as Title, terms, nowMs, target.end_date);
281    if (!endDate) return refused(NO_TERMS);
282    const after: MemberRow = { ...target, end_date: endDate, status: "active" };
283    await writeMemberChange(env, after, actor.email, audit(actor, "renew", email, target, after, nowMs));
284    return withSync(env, nowMs, `Renewed ${who} until ${endDate}.`, fetchImpl);
285  }
286
287  if (intent === "remove") {
288    const verdict = check(actor, { kind: "remove", target }, rules);
289    if (!verdict.ok) return refused(verdict.reason);
290    if (field(form, "confirmed") !== "yes") return { confirm: { email: target.email, name: who } };
291    const after: MemberRow = { ...target, status: "removed" };
292    await writeMemberChange(env, after, actor.email, audit(actor, "remove", email, target, after, nowMs));
293    return withSync(env, nowMs, `Removed ${who}.`, fetchImpl);
294  }
295
296  return refused(`Unknown action: ${intent || "none"}.`);
297}
298
299/** checkChange, with the one throw it can make (no term date entered yet) read as a refusal. */
300function check(actor: Actor, change: Parameters<typeof checkChange>[1], rules: Parameters<typeof checkChange>[2]) {
301  try {
302    return checkChange(actor, change, rules);
303  } catch (error) {
304    if (error instanceof RangeError) return { ok: false as const, reason: NO_TERMS };
305    throw error;
306  }
307}
308
309function audit(
310  actor: Actor,
311  action: "add" | "change_title" | "renew" | "remove",
312  email: string,
313  before: MemberRow | null,
314  after: MemberRow,
315  nowMs: number,
316  reason?: string,
317): MemberAuditRow {
318  return auditRow({ actor, action, email, before, after, nowMs, ...(reason ? { reason } : {}) });
319}
320
321/** The term review: Keep renews to the next term end, Remove removes; one batch, one sync. */
322async function review(env: Env, actor: Actor, form: FormData, nowMs: number, fetchImpl?: Fetch): Promise<MembersActionData> {
323  const terms = await listTerms(env);
324  const rules = rulesFor(env, terms, nowMs);
325  const changes: Array<{ after: MemberRow; audit: MemberAuditRow }> = [];
326  const notDone: string[] = [];
327  for (let i = 0; form.has(`email-${i}`); i += 1) {
328    const answer = field(form, `answer-${i}`);
329    if (answer !== "keep" && answer !== "remove") continue;
330    const target = await getMember(env, field(form, `email-${i}`).toLowerCase());
331    if (!target) continue;
332    const kind = answer === "keep" ? "renew" : "remove";
333    const verdict = check(actor, { kind, target }, rules);
334    if (!verdict.ok) {
335      notDone.push(`${target.name || target.email}: ${verdict.reason}`);
336      continue;
337    }
338    if (answer === "keep") {
339      const endDate = safeDefault(titleOf(target.title) as Title, terms, nowMs, target.end_date);
340      if (!endDate) {
341        notDone.push(`${target.name || target.email}: ${NO_TERMS}`);
342        continue;
343      }
344      const after: MemberRow = { ...target, end_date: endDate, status: "active" };
345      changes.push({ after, audit: { ...auditRow({ actor, action: "renew", email: target.email, before: target, after, nowMs }), action: "review_keep" } });
346    } else {
347      const after: MemberRow = { ...target, status: "removed" };
348      changes.push({ after, audit: auditRow({ actor, action: "remove", email: target.email, before: target, after, nowMs }) });
349    }
350  }
351  if (changes.length === 0) return refused(notDone.length ? notDone.join(" ") : "Nothing was answered, so nothing changed.");
352  await writeMemberChanges(env, changes);
353  const kept = changes.filter((c) => c.audit.action === "review_keep").length;
354  const done = `Review saved: ${kept} kept, ${changes.length - kept} removed.${notDone.length ? ` Not done: ${notDone.join(" ")}` : ""}`;
355  return withSync(env, nowMs, done, fetchImpl);
356}
357
358/**
359 * The Semester end dates line: the Primary Owner and Owners only. Dates separated by commas or spaces, each a real
360 * YYYY-MM-DD; the list replaces the old one, with a member_audit row holding both. No Access sync: a term date
361 * changes no one's access today.
362 */
363async function setTerms(env: Env, actor: Actor, text: string, nowMs: number): Promise<MembersActionData> {
364  if (!canEditTerms(actor)) return refused("Only an Owner sets the semester end dates.");
365  const dates = [...new Set(text.split(/[\s,;]+/).filter(Boolean))].sort();
366  const bad = dates.filter((d) => !isDate(d));
367  if (bad.length) return refused(`Not a date (YYYY-MM-DD): ${bad.join(", ")}.`);
368  const before = await listTerms(env);
369  await writeTerms(env, dates, actor.email, {
370    at: new Date(nowMs).toISOString(),
371    actor: actor.email,
372    actor_title: actor.title,
373    action: "set_terms",
374    member_email: null,
375    before: JSON.stringify(before),
376    after: JSON.stringify(dates),
377    reason: null,
378    cloudflare: "not_needed",
379  });
380  return { result: { ok: true, text: dates.length ? `Semester end dates: ${dates.join(", ")}.` : "Semester end dates cleared." } };
381}
382